--- title: "MCP Servers" description: "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](/api-reference/agents) 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 | Method | Path | Description | |--------|------|-------------| | `GET` | `/v1/mcp-servers` | List registered servers | | `POST` | `/v1/mcp-servers` | Register a server (syncs tools immediately) | | `GET` | `/v1/mcp-servers/{server_id}` | Retrieve one server | | `PATCH` | `/v1/mcp-servers/{server_id}` | Update (re-syncs when connection details change) | | `DELETE` | `/v1/mcp-servers/{server_id}` | Remove a server | | `POST` | `/v1/mcp-servers/{server_id}/sync-tools` | Re-fetch the server's tool list | | `POST` | `/v1/mcp` | ThunderPhone's own MCP endpoint (JSON-RPC) | `{server_id}` is the server's **UUID**. Writes require the `admin` role. ## MCP server object ```json { "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" } ``` | Field | Type | Description | |-------|------|-------------| | `id` | UUID | Server id | | `display_name` | string | 1–255 chars | | `url` | string | The server's streamable-HTTP endpoint. Must be `http(s)` and resolve **only to public IP addresses** (SSRF guard) | | `transport` | string | Only `streamable_http` is supported | | `headers` | array | Static headers sent on every connection. **Key names only** are returned (values are encrypted at rest and never leave the server), and only to `admin+` members — others see `[]` | | `enabled` | boolean | Disabled servers keep their config but their tools stop being offered to agents | | `last_tools_sync_at` | timestamp \| null | Last successful tool sync | | `cached_tools` | array | The synced tool list in OpenAI function format. Tool names are namespaced `mcp__` to avoid collisions; `mcp.tool_name` is the original name | --- ## Register a server ```bash cURL 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" }] }' ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | `display_name` | string | yes | ≤ 255 chars | | `url` | string | yes | ≤ 2048 chars; public-IP HTTPS/HTTP endpoint | | `transport` | string | no | `streamable_http` (the only value) | | `headers` | array of `{key, value}` | no | Header names must be unique (case-insensitive) | | `enabled` | boolean | no | Default `true` | 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](#mcp-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: | Category | Tools | | --- | --- | | Agents | `list_agents`, `get_agent`, `create_agent`, `update_agent`, `deploy_agent`, `discard_agent_draft`, `duplicate_agent`, `delete_agent`, `list_agent_versions` | | Phone numbers | `list_phone_numbers`, `get_phone_number_limits`, `provision_phone_number`, `list_voip_connections`, `search_voip_numbers`, `import_voip_numbers`, `update_phone_number`, `delete_phone_number` | | Calls | `list_calls`, `get_call`, `get_call_transcript`, `get_call_audio_url`, `get_call_grade`, `place_call`, `export_calls` | | Testing | `list_test_scenarios`, `create_test_scenario`, `generate_test_scenarios`, `run_agent_tests`, `get_test_run`, `list_validation_runs`, `get_validation_status` | | Knowledge | `list_knowledge_bases`, `create_knowledge_base`, `add_knowledge_document`, `import_knowledge_url`, `search_knowledge` | | Tools and webhooks | `list_integrations`, `create_integration`, `test_integration`, `list_webhook_endpoints`, `create_webhook_endpoint`, `test_webhook_endpoint`, `list_mcp_servers`, `create_mcp_server`, `sync_mcp_server_tools` | | Campaigns | `list_campaigns`, `create_campaign`, `add_campaign_contacts`, `campaign_action`, `get_campaign_stats` | | Voices | `list_voices`, `preview_voice`, `list_voice_clones` | | Billing | `get_billing_summary` (read-only; no payment mutation tools) | | Docs | `search_docs`, `get_doc_page` | 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](/guides/thunderphone-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: ```json Request { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "list_agents", "arguments": {} } } ``` ```json Response { "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 Attach servers to an agent with `mcp_server_ids`. Simple HTTP tools without an MCP server.