DelineaMCP

MCP server for the Delinea Secret Server and Platform APIs

Features

Automatic authentication against Secret Server
Extensive Secret Server tool set for managing folders, secrets, users, groups and roles. Includes inbox and access request helpers and coding agent utilities.
ChatGPT compatibility tools (search and fetch) for controlled AI interactions.
Optional Delinea Platform user management tools
Supports either Server Sent Events or STDIO transport modes
OAuth 2.0 with dynamic client registration per the MCP specification
TLS support for secure connections
Ready-to-run Docker image and development server entry point
Tested with ChatGPT, Claude Desktop, remote Claude connector, VSCode Copilot and openwebui

Installation

[!NOTE]

This project uses uv (https://github.com/astral-sh/uv), but if you prefer to run commands without this, you can do pip and venv commands as usual if desired.

Install Uv
Initialize project: uv pip sync requirements.txt
Use uv run server.py --config config.json

Configuration

Secrets such as passwords continue to come from environment variables. Provide DELINEA_PASSWORD in your shell environment. Optional features rely on additional variables such as AZURE_OPENAI_KEY or PLATFORM_SERVICE_PASSWORD.

Non-secret parameters belong in config.json:

{
  "delinea_username": "<username>",
  "delinea_base_url": "https://your-secret-server/SecretServer",
  "platform_hostname": "<tenant>.secureplatform.io",
  "platform_service_account": "<service_account>",
  "platform_tenant_id": "<tenant_id>",
  "azure_openai_endpoint": "https://example.openai.azure.com/",
  "azure_openai_deployment": "<deployment_name>",
  "auth_mode": "none",
  "transport_mode": "stdio",
  "chatgpt_disable_scope_checks": false,
  "port": 8000,
  "debug": false,
  "external_hostname": null,
  "ssl_keyfile": null,
  "ssl_certfile": null,
  "registration_psk": null,
  "jwt_key_path": ".cache/jwt.json",
  "oauth_db_path": ".cache/oauth.db",
  "enabled_tools": []
}

For Secret Server Cloud simply use the cloud URL without /SecretServer. Specify ssl_keyfile and ssl_certfile to enable HTTPS. For Let's Encrypt, use the privkey.pem and fullchain.pem files.

The configuration file supports the following keys:

delinea_username - Secret Server username. Must be a programmatic user with permission to do the tasks you want.
delinea_base_url - Base URL of your Secret Server instance.
platform_hostname - Platform tenant hostname (enables Platform tools).
platform_service_account - Service account used with the Platform API.
platform_tenant_id - Tenant ID for Platform API requests.
azure_openai_endpoint - Azure OpenAI endpoint. Only if you want the automatic report generation (most agents can generate their own report SQL so don't enable unless you need it).
azure_openai_deployment - Deployment name for Azure OpenAI.
auth_mode - Authentication mode (none or oauth). OAuth obviously doesn't work with stdio transport.
transport_mode - stdio for command line or sse for HTTP/SSE.
chatgpt_disable_scope_checks - Skip scope validation on ChatGPT requests. Enable only if you encounter problems connecting to ChatGPT.
port - Port for the HTTP server in sse mode.
debug - Enable verbose logging.
external_hostname - Hostname used when constructing OAuth token audiences. Don't add HTTP(S) prefix or port.
ssl_keyfile - Path to the SSL key for HTTPS. (eg privkey.pem)
ssl_certfile - Path to the SSL certificate for HTTPS. (eg fullchain.pem)
registration_psk - Pre-shared key required to register OAuth clients. You will need to type in this secret in your browser to approve OAuth connections.
jwt_key_path - Location of the RSA key pair used for OAuth tokens. Defaults to .cache/jwt.json. autogenerated if doesn't exist.
oauth_db_path - Path to the OAuth database file. Defaults to .cache/oauth.db. autogenerated if doesn't exist.
enabled_tools - List of tool names to register. An empty list enables all tools. It is highly recommended to enable tools selectively per use case or task. See docs/ folder for some examples.
search_objects - Allowed object types for the search tool. Defaults to ["secret"] but can include user, folder, group and role.
fetch_objects - Allowed object types for the fetch tool. Defaults to ["secret"] but can include the same values as search_objects.

Running the Server

Start the server locally in development mode:

python server.py

On startup the server requests a bearer token and stores it for subsequent API requests. This project will be expanded to integrate further with the Secret Server API.

MCP Tools

The server exposes several MCP tools for interacting with Secret Server:

run_report(sql_query, report_name=None) - create and execute a temporary report.
ai_generate_and_run_report(description) - generate SQL using Azure OpenAI and run it. Requires the Azure OpenAI variables.
list_example_reports() - list sample queries and table information.
get_secret(id, summary=False) - retrieve a secret or summary details.
get_folder(id) - fetch folder metadata and children.
search_users(query) - search active users.
search_secrets(query, lookup=False) - search or look up secrets.
search_folders(query, lookup=False) - search or look up folders.
get_secret_environment_variable(secret_id, environment) - output a script for fetching secret credentials in the specified shell.
check_secret_template(template_id) - fetch secret template details.
check_secret_template_field(template_id, field_id) - check if a template contains a field.
get_secret_template_field(field_id) - retrieve details about a specific secret template field by ID.
handle_access_request(request_id, status, response_comment, start_date=None, expiration_date=None) - approve or deny an access request.
get_pending_access_requests() - list pending access requests.
get_inbox_messages(read_status_filter=None, take=20, skip=0) - retrieve inbox messages.
mark_inbox_messages_read(message_ids, read=True) - mark messages as read or unread.
user_management(action, user_id=None, data=None, skip=0, take=20, is_exporting=False) - unified user operations. action accepts get, create, update, delete, list_sessions, reset_2fa, reset_password or lock_out. Provide user_id when required and supply the request body via data for create, update and password reset actions. Example: user_management("reset_password", user_id=42, data={"newPassword": "Pa$$w0rd"}).
role_management(action, role_id=None, data=None, params=None) - manage roles. action may be list, get, create or update. Pass optional query parameters with params when listing roles. Example: role_management("update", role_id=3, data={"name": "New Role"}).
user_role_management(action, user_id, role_ids=None) - assign or remove roles from a user. action is get, add or remove and role_ids is a list of role identifiers for add/remove operations.
group_management(action, group_id=None, data=None, params=None) - handle groups. action may be get, list, create or delete. Provide group_id for get/delete and data when creating a group.
folder_management(action, folder_id=None, data=None, params=None) - manage folders. action may be get, list, create, update or delete. Provide folder_id for get, update or delete and supply data when creating or updating a folder.
user_group_management(action, user_id, group_ids=None) - manage group membership for a user. action is get, add or remove. Supply a list of group_ids when adding or removing membership.
group_role_management(action, group_id, role_ids=None) - control roles on a group. Use list, add or remove actions. Provide role_ids when adding or removing.
health_check() - query the Secret Server health check endpoint and return the current service status.

Use the server configuration variables described above to authenticate. The AI tool is automatically disabled if the Azure OpenAI variables are missing. Only the tool names listed in config.json will be registered. An empty list enables every tool.

Use Cases

The documentation covers several workflows for connecting tools to the server:

ChatGPT Custom Connector
Claude Desktop
Remote Claude Connector
openwebui for Administration
VSCode Copilot

Docker Quickstart

A Dockerfile is provided for running the MCP server without installing Python dependencies locally.

Build the image:

docker build -t dev.local/delinea-mcp:latest .

Run the server (pass your credentials via environment variables):

docker run --rm -p 8000:8000 \
  -e DELINEA_PASSWORD=<password> \
  -e PLATFORM_SERVICE_PASSWORD=<password> \
  -e DELINEA_DEBUG=1 \
  -e AZURE_OPENAI_KEY=<your-key-or-appropriate-token> \
  -v $(pwd)/config.json:/app/config.json:ro \
  -v mcp-data:/app/data \
  dev.local/delinea-mcp:latest

Populate config.json with your usernames and URLs as shown above.

The container stores oauth.db and jwt.json in /app/data. Mount a volume (shown as mcp-data above) so these files and any HTTPS certificates persist between runs.

Replace <https://your-secret-server/SecretServer> with the base URL of your Secret Server instance to avoid connection errors.

The server will start on port 8000 by default using python server.py. Set the port option in config.json to override the default. Enable debug: true to log all incoming HTTP requests.

Example Scripts

The manual_secret_request.py script shows how to retrieve an OAuth token for a specific secret ID:

python scripts/manual_secret_request.py <Secret_ID>

Set the environment variables SECRET_USERNAME_<id> and SECRET_PASSWORD_<id> for the secret before running the script. Optionally set DELINEA_BASE_URL to override the default https://localhost/SecretServer.

Running Tests

Run the unit tests with coverage to ensure 100% code coverage:

pip install -r requirements.txt
coverage run -m pytest -q
coverage report --omit "tests/*"

Live Testing

Some integration tests require valid credentials. Set the following environment variables and the optional LIVE_SECRET_ID before running the suite:

export DELINEA_PASSWORD=<password>
# Optional secret used by tests/test_live.py
export LIVE_SECRET_ID=<id>
export SECRET_USERNAME_<id>=<secret_username>
export SECRET_PASSWORD_<id>=<secret_password>

When these variables are present the live tests will perform real API requests.

Production Deployment

Dependencies are pinned in requirements.txt and releases are tagged using Semantic Versioning. Build the Docker image from a tagged commit and deploy it to your production environment, passing the required environment variables (DELINEA_USERNAME, DELINEA_PASSWORD, optionally DELINEA_BASE_URL). Optional features rely on additional variables:

PLATFORM_SERVICE_PASSWORD along with PLATFORM_HOSTNAME, PLATFORM_SERVICE_ACCOUNT, and PLATFORM_TENANT_ID enables the user management tools.
AZURE_OPENAI_KEY together with AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT enables the AI report generation helper.

When running with OAuth or SSE transport you may need to provide registration_psk and configure an external_hostname or HTTPS certificate files.

Repository Layout

delinea_mcp/ - package containing MCP tools.
server.py - thin entry point that registers everything with the MCP server.
docs/ - project documentation and the generated delinea-secret-server-openapi-spec.json.
scripts/ - helper examples including manual_secret_request.py.

Security Considerations

The included OAuth endpoints are intended for development and testing. The /oauth/authorize route accepts any redirect_uri and will redirect the user without validation. Deployments must restrict this value to approved callback URLs; otherwise attackers could supply a malicious URL and capture authorization codes. See Open Redirection for background.

Release Notes

See docs/release_notes.md for a summary of the latest features and roadmap items.

Roadmap

Passthrough authentication
Streaming HTTP transport support
Expand tool coverage on the Delinea Platform and add other Delinea products

Contributing

Contributions are welcome! Please open issues or pull requests for any improvements. All new code should include unit tests and pass the existing test suite.

License

This project is licensed under the MIT License.