# delineaxpm/delinea-mcp architecture

> Architecture diagram of the GitHub repository delineaxpm/delinea-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/delineaxpm/delinea-mcp
- Repository: https://github.com/delineaxpm/delinea-mcp

## Overview

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`](https://github.com/delineaxpm/delinea-mcp/blob/main/server.py) (server.py), [`delinea_mcp/tools.py`](https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/tools.py) (Tools), [`delinea_mcp/auth/routes.py`](https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/auth/routes.py) (Auth routes), [`delinea_mcp/config.py`](https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/config.py) (Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime core"]
  node_server_py["server.py<br/>bootstrap<br/>[server.py]"]
  node_config_py["Config<br/>[config.py]"]
  node_constants_py["Constants<br/>[constants.py]"]
  node_tools_py["Tools<br/>[tools.py]"]
  node_user_platform_tools_py["Platform tools<br/>admin tools"]
  node_session_py["Session<br/>[session.py]"]
  node_sse_py["SSE transport<br/>http transport<br/>[sse.py]"]
end

subgraph group_auth["Auth subsystem"]
  node_auth_routes_py["Auth routes<br/>oauth endpoints<br/>[routes.py]"]
  node_as_config_py["Auth config<br/>[as_config.py]"]
  node_validators_py["Validators<br/>request validation<br/>[validators.py]"]
end

subgraph group_integrations["External systems"]
  node_delinea_api_py["API helper<br/>secret server api<br/>[delinea_api.py]"]
  node_mcp_client(("MCP client<br/>external client"))
  node_secret_server[("Secret Server<br/>external system")]
  node_delinea_platform[("Platform<br/>external system")]
  node_azure_openai(("Azure OpenAI<br/>ai service"))
end

subgraph group_support["Support files"]
  node_config_json_example["Config example<br/>deployment config"]
  node_oauth_state[("Auth state<br/>persistent store")]
end

node_server_py -->|"loads"| node_config_py
node_server_py -->|"starts"| node_tools_py
node_server_py -->|"enables"| node_sse_py
node_server_py -->|"mounts"| node_auth_routes_py
node_server_py -->|"serves"| node_mcp_client
node_config_py -->|"uses"| node_constants_py
node_config_py -->|"maps"| node_config_json_example
node_tools_py -->|"calls"| node_session_py
node_tools_py -->|"delegates"| node_delinea_api_py
node_tools_py -->|"reads/writes"| node_secret_server
node_user_platform_tools_py -->|"administers"| node_delinea_platform
node_user_platform_tools_py -->|"extends"| node_tools_py
node_tools_py -->|"generates SQL"| node_azure_openai
node_azure_openai -->|"executes report"| node_secret_server
node_auth_routes_py -->|"publishes"| node_as_config_py
node_auth_routes_py -->|"validates"| node_validators_py
node_auth_routes_py -->|"persists"| node_oauth_state
node_sse_py -->|"streams"| node_mcp_client
node_server_py -->|"depends on"| node_oauth_state

click node_server_py "https://github.com/delineaxpm/delinea-mcp/blob/main/server.py"
click node_config_py "https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/config.py"
click node_constants_py "https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/constants.py"
click node_tools_py "https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/tools.py"
click node_user_platform_tools_py "https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/user_platform_tools.py"
click node_session_py "https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/session.py"
click node_delinea_api_py "https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_api.py"
click node_sse_py "https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/transports/sse.py"
click node_auth_routes_py "https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/auth/routes.py"
click node_as_config_py "https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/auth/as_config.py"
click node_validators_py "https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/auth/validators.py"
click node_config_json_example "https://github.com/delineaxpm/delinea-mcp/blob/main/config.json.example"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_py,node_config_py,node_constants_py,node_tools_py,node_user_platform_tools_py,node_session_py,node_sse_py toneBlue
class node_auth_routes_py,node_as_config_py,node_validators_py toneAmber
class node_delinea_api_py,node_mcp_client,node_secret_server,node_delinea_platform,node_azure_openai toneMint
class node_config_json_example,node_oauth_state toneRose
```

## Components

### Runtime core

Entry point, transport, config, and MCP tool dispatch.

- [server.py](https://github.com/delineaxpm/delinea-mcp/blob/main/server.py): bootstrap · Thin process entry point for starting the MCP server. · `server.py`
- [Config](https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/config.py): runtime config · Loads runtime settings and environment-driven secrets. · `delinea_mcp/config.py`
- [Constants](https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/constants.py): runtime constants · Shared names, defaults, and configuration constants. · `delinea_mcp/constants.py`
- [Tools](https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/tools.py): mcp tools · Primary MCP tool registry and Secret Server-facing handlers. · `delinea_mcp/tools.py`
- [Platform tools](https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/user_platform_tools.py): admin tools · Optional Delinea Platform user, group, and role workflows. · `delinea_mcp/user_platform_tools.py`
- [Session](https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/session.py): api session · Authenticated session state and bearer-token handling for Delinea APIs. · `delinea_mcp/session.py`
- [SSE transport](https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/transports/sse.py): http 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](https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/auth/routes.py): oauth endpoints · OAuth 2.0 and dynamic registration HTTP endpoints. · `delinea_mcp/auth/routes.py`
- [Auth config](https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/auth/as_config.py): oauth config · Builds authorization-server configuration and metadata. · `delinea_mcp/auth/as_config.py`
- [Validators](https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_mcp/auth/validators.py): request validation · 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](https://github.com/delineaxpm/delinea-mcp/blob/main/delinea_api.py): secret server api · Low-level client helpers for Delinea Secret Server requests. · `delinea_api.py`
- **MCP client**: external client · Local or remote agent connecting over STDIO or SSE.
- **Secret Server**: external system · Primary Delinea Secret Server backend for secrets, folders, reports, and requests.
- **Platform**: external system · Optional Delinea Platform backend for user and role administration.
- **Azure OpenAI**: ai service · Used to generate SQL for AI-assisted report execution.

### Support files

Deployment and configuration artifacts that shape runtime behavior.

- [Config example](https://github.com/delineaxpm/delinea-mcp/blob/main/config.json.example): deployment config · Example non-secret runtime configuration template. · `config.json.example`
- **Auth state**: persistent store · JWT key and OAuth database files persisted across restarts.

## Connections

- 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.