HTTP API

MCP Director exposes a JSON-RPC 2.0 MCP endpoint over streamable HTTP, plus OAuth/OIDC endpoints and an admin API.

Base URL

• Default: http://127.0.0.1:3000
• MCP endpoints: /sse and /mcp

Protocol Version Header

All MCP HTTP requests must include the MCP-Protocol-Version header.

Version	Status
2025-11-25	Default
2025-06-18	Supported
2025-03-26	Supported
2024-11-05	Supported

Authentication

OAuth 2.1 (PKCE)

MCP Director implements OAuth 2.1 Authorization Code with PKCE (S256).

Endpoint	Description
GET /authorize	Begin authorization flow
POST /authorize	Submit consent decision
POST /token	Exchange code for access token
POST /register	Register OAuth clients
/.well-known/oauth-authorization-server	OAuth metadata
/.well-known/openid-configuration	OIDC metadata

Profile Tokens

If profile auth is enabled, provide a token via:

• Query: /sse?profile=restricted&token=...
• Header: Authorization: Bearer <token>

Admin API Auth

The /api admin endpoints use HTTP Basic Auth when settings.auth.enabled is true.

MCP Transport

GET /sse

Opens the SSE event stream. The server sends an endpoint event with the session-specific POST URL.

Headers:

• MCP-Protocol-Version: 2025-11-25
• Authorization: Bearer <token> (optional)

Query params:

• profile: optional profile name
• project: optional project name
• token: optional profile token

Response:

• text/event-stream
• First event: event: endpoint with data /mcp?sessionId=<id>

POST /mcp

Send MCP JSON-RPC requests.

Headers:

• MCP-Protocol-Version: 2025-11-25
• Authorization: Bearer <token> (optional)

Query params:

• sessionId: optional session ID (provided by /sse)

Example - ping:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "ping"
}

Example - initialize:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "clientInfo": { "name": "example", "version": "0.0.1" }
  }
}

Key MCP Methods

Method	Description
tools/list	List available tools
tools/call	Call a tool
resources/list	List resources
resources/read	Read a resource
resources/subscribe	Subscribe to resource updates
prompts/list	List prompts
prompts/get	Get a prompt
tasks/result	Get async task result
tasks/list	List tasks
tasks/cancel	Cancel a task
ping	Health check

Async Tool Calls

Include a task object in tools/call params to run asynchronously:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "filesystem/read_file",
    "arguments": { "path": "/tmp/notes.txt" },
    "task": { "timeoutMs": 300000 }
  }
}

Check status:

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tasks/result",
  "params": { "taskId": "<id>" }
}

SSE Notifications

The SSE stream carries notifications:

• notifications/tools/list_changed
• notifications/resources/list_changed
• notifications/prompts/list_changed
• notifications/resources/updated
• notifications/progress
• notifications/cancelled
• notifications/shutdown

Observability

Endpoint	Description
GET /metrics	Prometheus-style counters
GET /health	Backend + analytics health
GET /api-docs	OpenAPI 3.0 document

Admin API

All endpoints are under /api and require Basic Auth when enabled.

Servers

Endpoint	Description
GET /api/servers	List servers
POST /api/servers	Add server
DELETE /api/servers/{name}	Remove server
GET /api/servers/{name}/status	Server status

Tools

Endpoint	Description
GET /api/tools	List all tools

Profiles

Endpoint	Description
GET /api/profiles	List profiles
POST /api/profiles	Create profile
DELETE /api/profiles/{name}	Delete profile

Projects

Endpoint	Description
GET /api/projects	List projects
POST /api/projects	Create project
DELETE /api/projects/{name}	Delete project

Configuration

Endpoint	Description
GET /api/config	Get configuration
POST /api/config	Update configuration
POST /api/config/reload	Reload configuration

Authentication

Endpoint	Description
POST /api/auth/enable	Enable auth with username/password

Error Handling

Status	Description
400	Invalid request or unsupported protocol version
403	Invalid origin header
429	Rate limit exceeded

JSON-RPC errors follow MCP spec codes: -32600, -32602, -32603.