MCP Servers

Attach remote MCP tool servers to your agents, and use ThunderPhone itself as an MCP server.

Two directions of MCP (Model Context Protocol) integration:

1. Remote MCP servers (/v1/mcp-servers) — register an external MCP server; its tools are synced, cached, and become callable by any agent you attach the server to via mcp_server_ids.
2. ThunderPhone as an MCP server (POST /v1/mcp) — a single endpoint that speaks MCP (JSON-RPC over Streamable HTTP), letting Claude, coding IDEs, and agent frameworks build, test, validate, and operate your voice agents. Authenticate with your sk_live_ key.

Endpoints#

{server_id} is the server's UUID. Writes require the admin role.

MCP server object#

{
  "id": "1c9d2e4f-…",
  "display_name": "Internal ops tools",
  "url": "https://mcp.example.com/mcp",
  "transport": "streamable_http",
  "headers": [{ "key": "Authorization" }],
  "enabled": true,
  "last_tools_sync_at": "2026-04-20T18:24:10.113Z",
  "cached_tools": [
    {
      "type": "function",
      "function": {
        "name": "mcp_1c9d2e4f…_create_ticket",
        "description": "Create a support ticket",
        "parameters": { "type": "object", "properties": { "…": {} } }
      },
      "mcp": { "server_id": "1c9d2e4f-…", "tool_name": "create_ticket" }
    }
  ],
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

Register a server#

curl -X POST https://api.thunderphone.com/v1/mcp-servers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Internal ops tools",
    "url": "https://mcp.example.com/mcp",
    "headers": [{ "key": "Authorization", "value": "Bearer secret-token" }]
  }'

The create connects to the server and syncs its tools inline — if the server is unreachable or the MCP handshake fails, the request fails with 400 ({"url": "Unable to synchronize MCP tools: …"}) and nothing is saved. Returns 201 Created with the server object.

Update / delete / re-sync#

PATCH accepts any subset of the create fields. Changing display_name, url, transport, or headers triggers a re-sync (same 400 on failure). When updating headers, an entry with an empty value keeps the existing stored value for that key — so you can reorder/rename without re-sending secrets.

DELETE returns 204 No Content (agents attached to the server simply lose those tools).

POST /v1/mcp-servers/{id}/sync-tools re-fetches the tool list and returns the updated server object — call it after deploying new tools to your MCP server.

ThunderPhone as an MCP server#

POST /v1/mcp is a stateless Streamable HTTP MCP endpoint. It supports protocol versions 2025-06-18 and 2025-03-26, plus initialize, ping, tools, prompts, resources, and notifications. Point a client at https://api.thunderphone.com/v1/mcp with an sk_live_ organization API key as its Bearer token. Session cookies and publishable widget keys are not accepted.

The server exposes 59 tools across these categories:

Every tool has title and MCP safety annotations. Product tools dispatch through the same REST views as the public API, retaining organization scoping, roles, validation, billing admission, quotas, outbound TCPA confirmation, provider safety, and audit behavior. See Use ThunderPhone as an MCP server for full arguments, annotations, prompts, resources, and configuration examples.

Five starter prompts cover receptionist creation, test execution, number provisioning, low-grade call review, and knowledge URL attachment. Resources expose thunderphone://docs/llms.txt, thunderphone://docs/quickstart, and thunderphone://pricing.

Example tools/call exchange:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": { "name": "list_agents", "arguments": {} }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "[{\"id\": 12, \"name\": \"Customer Support Agent\", …}]" }],
    "structuredContent": [{ "id": 12, "name": "Customer Support Agent" }],
    "isError": false
  }
}

Tool errors are reported in-band (isError: true) as a short sentence plus a JSON block containing code, detail, and an actionable next_step. Unknown JSON-RPC methods return -32601 in an HTTP 200 response. Notifications return 202 Accepted; JSON-RPC batches return -32600; and unsupported GET or DELETE requests return 405 Method Not Allowed with Allow: POST.

Related#