MCP tools API

Register Model Context Protocol servers and configure per-agent access and per-tool approval policy. Requires Owner or Admin. See Concepts — MCP tools for the runtime story.

List MCP servers

GET /api/mcp-servers

200 OK
{
  "items": [
    {
      "id": "mcp_01",
      "name": "Zapier",
      "url": "https://mcp.zapier.com/v1/.../sse",
      "active": true,
      "lastProbedAt": "2026-05-25T11:00:00.000Z",
      "toolCount": 312
    }
  ]
}

Register a new MCP server

POST /api/mcp-servers

Request body
{
  "name": "Custom HubSpot MCP",
  "url": "https://hubspot-mcp.acme.com/sse"
}

200 OK
{ "id": "mcp_02", "name": "Custom HubSpot MCP", "active": true,
  "toolCount": 18 }

400 Bad Request
{ "error": "unsafe_mcp_url",
  "detail": "Hostname not in allowlist / private IP rejected" }

400 Bad Request
{ "error": "mcp_probe_failed",
  "detail": "Server did not respond to introspection within 10s" }

The platform validates the URL against the SSRF block list (private IP, loopback, non-https in prod) before any outbound call. On success it opens the MCP connection, probes the tool list, and stores the resolved tool catalogue.

Update an MCP server

PATCH /api/mcp-servers/:id

Request body (partial)
{ "active": false }

200 OK
{ "id": "mcp_02", "active": false }

Delete an MCP server

DELETE /api/mcp-servers/:id

200 OK
{ "id": "mcp_02", "deleted": true }

Re-probe a server

POST /api/mcp-servers/:id/test — trigger a fresh introspection. Useful after upstream tool changes.

200 OK
{ "ok": true, "toolCount": 312, "latencyMs": 442 }

200 OK (degraded)
{ "ok": false, "error": "auth_failed" }

Per-agent allowlist

GET /api/agents/:slug/mcp-servers — list the servers this agent can talk to.
PUT /api/agents/:slug/mcp-servers/:serverId — toggle on or off.

Request body
{ "allowed": true }

200 OK
{ "serverId": "mcp_01", "allowed": true }

Resolved tool catalogue

GET /api/agents/:slug/mcp-tools — returns the agent's full tool catalogue, with namespace prefixes and per-tool gating policy:

200 OK
{
  "items": [
    {
      "name": "zapier:hubspot_create_contact",
      "description": "Create a new contact in HubSpot",
      "approvalPolicy": "single_approval"
    },
    {
      "name": "zapier:gmail_search_threads",
      "description": "Search Gmail threads",
      "approvalPolicy": "no_gate"
    }
  ]
}

Bootstrap Zapier MCP

POST /api/mcp-servers/bootstrap-zapier — one-shot helper that takes a Zapier MCP URL, validates SSRF safety, registers the server, probes the tool list, and returns the new row. The Tenant onboarding wizard calls this.

Source: src/platform/mcp-api.ts, src/platform/mcp-policy-api.ts.