How delineaxpm/delinea-mcp works
1. What this repo is
- DelineaMCP is a Python MCP server that brokers AI client requests to Delinea Secret Server, with optional Delinea Platform administration tools.
- It is not a generic web app: the core product boundary is “MCP client on one side, Delinea APIs on the other.”
2. Runtime entry point and modes
- server.py is the thin bootstrap entry point.
- The server can run in two transport modes: STDIO for local agent integrations and SSE over HTTP/S for remote/networked clients.
- The SSE transport implementation lives in delinea_mcp/transports/sse.py.
3. MCP surface / tool registry
- delinea_mcp/tools.py and delinea_mcp/user_platform_tools.py define the MCP tool set exposed to clients.
- Tools are registered selectively via config (enabled_tools), or all are enabled when that list is empty.
- The tool surface covers secret lookup, folder operations, reports, inbox/access-request helpers, and user/group/role management.
4. Secret Server integration layer
- delinea_api.py is the low-level API helper for talking to Delinea Secret Server.
- delinea_mcp/session.py manages authenticated session state, including the bearer token flow described in the README.
- Most tool calls flow through this session/API layer before returning MCP responses.
5. Authentication and OAuth subsystem
- delinea_mcp/auth/ contains the OAuth 2.0 / MCP dynamic registration implementation:
- routes.py exposes the auth endpoints.
- as_config.py builds authorization-server-related configuration.
- validators.py performs request validation.
- The auth system persists state using the paths in config (jwt_key_path, oauth_db_path), which are also important runtime artifacts.
6. Configuration boundary
- delinea_mcp/config.py, delinea_mcp/constants.py, and config.json define runtime behavior.
- Non-secret settings live in JSON; secrets come from environment variables like DELINEA_PASSWORD, PLATFORM_SERVICE_PASSWORD, and AZURE_OPENAI_KEY.
- This separation matters architecturally because the server is designed to be deployed with immutable config plus injected secrets.
7. Optional Delinea Platform subsystem
- delinea_mcp/user_platform_tools.py is a separate, optional branch of functionality for Delinea Platform user/group/role administration.
- It is enabled only when the Platform connection settings are present (platform_hostname, platform_service_account, platform_tenant_id, and password).
- This is a distinct external dependency from Secret Server, not just another Secret Server endpoint.
8. AI-assisted report generation path
- The ai_generate_and_run_report tool is gated by Azure OpenAI configuration.
- When enabled, tool execution includes an external call to Azure OpenAI to generate SQL, then a second call into Secret Server to execute the report.
- This creates a two-hop flow: MCP client → server → OpenAI → server → Secret Server.
9. Main data flow for a typical tool request
- An MCP client connects over STDIO or SSE.
- If OAuth is enabled, the auth routes complete client registration/login and issue tokens.
- The selected tool handler validates input, uses the session/API layer to call Secret Server or Platform, and returns the result back through the MCP transport.
10. Transport and deployment boundaries
- The server supports HTTPS via ssl_keyfile/ssl_certfile, with external_hostname used to construct OAuth audiences.
- The Docker image and server.py are the main operational entry points for deployment.
- Persistent auth state must survive restarts; the README calls out mounting storage for the JWT and OAuth DB files.
11. Tool categories worth diagramming separately
- Secret retrieval/search: get_secret, search_secrets, search_folders, search_users, get_folder.
- Admin workflows: user_management, group_management, role_management, membership/role assignment tools.
- Security workflow helpers: access requests, inbox messages, health check, template inspection, and environment-variable script generation.
- Report workflow: manual SQL reports and AI-generated reports.
12. Repo support structure
- tests/ mirrors the runtime surfaces: API, OAuth, SSE routes, tool behavior, validation, and live integration tests.
- docs/ captures connector-specific deployment guidance, plus the MCP/security notes that matter for correct external integration.
- These directories don’t change runtime architecture, but they confirm the repo is organized around transport, auth, tools, and external API integration as the main seams.
Main entry points: server.py server.py · tools.py Tools · routes.py Auth routes · config.py Config
Components 17
Runtime core
Entry point, transport, config, and MCP tool dispatch.
- server.py · Thin process entry point for starting the MCP server.
server.py - Config · Loads runtime settings and environment-driven secrets.
delinea_mcp/config.py - Constants · Shared names, defaults, and configuration constants.
delinea_mcp/constants.py - Tools · Primary MCP tool registry and Secret Server-facing handlers.
delinea_mcp/tools.py - Platform tools · Optional Delinea Platform user, group, and role workflows.
delinea_mcp/user_platform_tools.py - Session · Authenticated session state and bearer-token handling for Delinea APIs.
delinea_mcp/session.py - SSE transport · Server-Sent Events transport for remote MCP clients.
delinea_mcp/transports/sse.py
Auth subsystem
OAuth and dynamic client registration for MCP access.
- Auth routes · OAuth 2.0 and dynamic registration HTTP endpoints.
delinea_mcp/auth/routes.py - Auth config · Builds authorization-server configuration and metadata.
delinea_mcp/auth/as_config.py - Validators · Validates auth and registration requests.
delinea_mcp/auth/validators.py
External systems
Secret Server, Delinea Platform, and AI services reached by the server.
- API helper · Low-level client helpers for Delinea Secret Server requests.
delinea_api.py - MCP client · Local or remote agent connecting over STDIO or SSE.
- Secret Server · Primary Delinea Secret Server backend for secrets, folders, reports, and requests.
- Platform · Optional Delinea Platform backend for user and role administration.
- Azure OpenAI · Used to generate SQL for AI-assisted report execution.
Support files
Deployment and configuration artifacts that shape runtime behavior.
- Config example · Example non-secret runtime configuration template.
config.json.example - Auth state · JWT key and OAuth database files persisted across restarts.
Connections 19
- server.py → Config: loads · Bootstrapping reads runtime configuration before serving.
- server.py → Tools: starts · The entry point wires the MCP tool surface into the server.
- server.py → SSE transport: enables · Optional HTTP/SSE transport path for remote clients.
- server.py → Auth routes: mounts · OAuth endpoints are exposed when auth is enabled.
- server.py → MCP client: serves · Accepts MCP connections from local or remote clients.
- Config → Constants: uses · Configuration is interpreted with shared defaults and names.
- Config → Config example: maps · Non-secret settings are supplied through the JSON config file.
- Tools → Session: calls · Tool handlers route requests through the authenticated session layer.
- Tools → API helper: delegates · Secret Server operations flow into the API helper.
- Tools → Secret Server: reads/writes · Secret lookup, search, reports, and request workflows reach Secret Server.
- Platform tools → Platform: administers · Optional user, group, and role management targets Delinea Platform.
- Platform tools → Tools: extends · Platform-specific tools sit beside the core MCP tool set.
- Tools → Azure OpenAI: generates SQL · AI-assisted report tools can call Azure OpenAI before execution.
- Azure OpenAI → Secret Server: executes report · Generated SQL is then sent back to Secret Server for report runs.
- Auth routes → Auth config: publishes · Routes expose authorization-server metadata and settings.
- Auth routes → Validators: validates · Incoming OAuth and registration requests are checked.
- Auth routes → Auth state: persists · Auth flows store keys and registration state durably.
- SSE transport → MCP client: streams · SSE transport carries MCP messages over HTTP/S.
- server.py → Auth state: depends on · Persistent auth artifacts must survive server restarts.