Agents

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), exposing your org's agents and calls as tools to any MCP client (Claude, IDEs, agent frameworks). 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 implements MCP's JSON-RPC methods: initialize, notifications/initialized, tools/list, and tools/call. Point any MCP client at https://api.thunderphone.com/v1/mcp with your API key as a Bearer token (this endpoint accepts only sk_live_ keys — no session auth).

Available tools:

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\", …}]" }],
    "isError": false
  }
}

Tool errors are reported in-band (isError: true); unknown JSON-RPC methods return a -32601 error with HTTP 400.

Related#