mcp.*
MCP server management RPC methods
mcp.* is the runtime surface for the MCP plugin host. The handler module is src/gateway/handlers/mcp.rs, and the nine core methods are wired by register_mcp_handlers only when the McpManagerActor starts up. In simulated mode (no MCP actor), the namespace is absent and every mcp.* call returns Method not found. The three approval methods are registered directly inside HandlerRegistry::new() as stubs — they currently log a marker and return success.
mcp_config.* is the Settings-page CRUD surface for MCP servers; it lives alongside the runtime methods and is registered only when the MCP manager exists.
Methods
mcp.list
List every configured MCP server and its live status (id, name, transport, status, healthy, tools/resources/prompts counts).
Request: no params.
Response: { "servers": [ ...ServerInfo... ] }. Each ServerInfo carries the live pid, uptime_seconds, and restart_count as reported by the MCP actor.
mcp.add
Add a new MCP server configuration.
| Parameter | Type | Required | Description |
|---|---|---|---|
config | object | yes | The full McpManagerConfig row — see Config Fields. |
Response: { "ok": true } on success; INTERNAL_ERROR with the actor's message otherwise.
mcp.update
Upsert an existing MCP server. Removes the old id and re-adds the new config; on failure, rolls back to the prior config if one existed.
| Parameter | Type | Required | Description |
|---|---|---|---|
config | object | yes | The new McpManagerConfig row. |
Response: { "ok": true } on success.
mcp.delete
Delete an MCP server configuration.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Server id |
Response: { "ok": true }.
mcp.status
Detailed status of a single MCP server, including live pid, uptime_seconds, and restart_count.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Server id |
Response: the full ServerStatus object, or RESOURCE_NOT_FOUND (-32004) when the id is unknown.
mcp.logs
Tail the most recent logs for a server. The MCP actor does not keep a log buffer; this handler returns an empty list with implemented: false so a client can distinguish "no logs" from "the implementation is missing".
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Server id |
max_lines | number | no | Defaults to 100 |
Response: { "logs": [], "implemented": false }.
mcp.start
Start a stopped MCP server.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Server id |
Response: { "ok": true }.
mcp.stop
Stop a running MCP server.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Server id |
Response: { "ok": true }.
mcp.restart
Stop, then start, an MCP server.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | yes | Server id |
Response: { "ok": true }.
mcp.tools
List the tools advertised by every healthy MCP server, aggregated across the host. Request: no params. Response: { "tools": [ ...Tool... ] }. Each row carries name, description, and server.
mcp.resources
List the resources advertised by every healthy MCP server. Response: { "resources": [ ...Resource... ] }.
mcp.prompts
List the prompts advertised by every healthy MCP server. Response: { "prompts": [ ...Prompt... ] }.
mcp.list_pending_approvals
List every approval request still awaiting a user response. Stub implementation; returns an empty array because the approval handler integration is pending. Registered directly inside HandlerRegistry::new() so it is always present, regardless of whether the MCP actor is up.
Response: { "result": [] }.
mcp.respond_approval
Submit a user's response to an approval request. Stub implementation; logs a marker and returns success.
| Parameter | Type | Required | Description |
|---|---|---|---|
request_id | string | yes | Approval request id |
approved | boolean | yes | Whether the user approved |
reason | string | no | Free-text reason |
Response: { "success": true }.
mcp.cancel_approval
Cancel a pending approval request. Stub implementation; logs a marker and returns success.
| Parameter | Type | Required | Description |
|---|---|---|---|
request_id | string | yes | Approval request id |
Response: { "success": true }.
Config Fields
mcp.add and mcp.update take the full McpManagerConfig row:
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Unique server id |
name | string | yes | Display name |
transport | string | yes | stdio / http / sse (defaults to stdio) |
command | string | stdio only | Command to run for stdio transport |
args | string[] | no | Args for the stdio command |
url | string | http / sse | Endpoint URL |
env | object | no | Env vars for the stdio process |
requires_runtime | string | no | node / python / bun etc. |
auto_start | boolean | no | Defaults to true |
timeout_seconds | number | no | Per-request timeout |
tool_filter | object | no | Optional allow/deny filter over advertised tools |
The actor silently no-ops on a McpStdio install whose command is missing on disk (since 26.6.23).
mcp_config.* (Settings CRUD)
mcp_config.* is the Settings-page companion. It is registered in register_mcp_config_handlers next to the runtime methods.
| Method | Purpose |
|---|---|
mcp_config.list | List MCP server config rows (the persisted shape, not live status) |
mcp_config.get | Fetch a single config row by id |
mcp_config.create | Add a new config row, with API-key secrets written to the vault |
mcp_config.update | Update an existing config row |
mcp_config.delete | Delete a config row |
The Settings page edits through mcp_config.*; the runtime mcp.* surface reflects the resulting live state.
See Also
- Methods Reference -- All currently registered namespaces
- Extensions Store --
extensions.*is the unified façade overmcp.*/plugin.*/skills.*