> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use ThunderPhone as an MCP server

> Connect any Streamable HTTP MCP client to ThunderPhone to list agents, inspect calls and transcripts, and place outbound calls with an organization API key.

ThunderPhone exposes a Model Context Protocol server at:

```text theme={null}
https://api.thunderphone.com/v1/mcp
```

Point an MCP client at that Streamable HTTP endpoint to make your organization's
agents and calls available as tools. This is the opposite direction from
[connecting a remote MCP server to a voice agent](/guides/mcp-servers):

| Direction                              | Result                                                            |
| -------------------------------------- | ----------------------------------------------------------------- |
| Remote MCP server → ThunderPhone agent | Your voice agent can call the remote server's tools.              |
| ThunderPhone → your MCP client         | Your MCP client can call ThunderPhone tools for agents and calls. |

## Authenticate

Create an `sk_live_` key under **Organization → Keys** and send it as a Bearer
token. The MCP endpoint accepts organization API keys, not dashboard session
cookies or publishable widget keys.

```json Generic client configuration theme={null}
{
  "mcpServers": {
    "thunderphone": {
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_YOUR_API_KEY"
      }
    }
  }
}
```

<Warning>
  An `sk_live_` key can access organization data and place calls. Keep it out of
  browser code, repositories, screenshots, and chat logs. Use a secret store
  supported by your MCP client and revoke a key immediately if exposed.
</Warning>

## Available tools

| Tool                  | Arguments                                   | What it does                                                                                  |
| --------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `list_agents`         | none                                        | Lists organization agents with id, name, product, and voice.                                  |
| `get_agent`           | `agent_id`                                  | Retrieves one agent.                                                                          |
| `place_call`          | `agent_id`, `from_number`, `to_number`      | Places an outbound call with the same validation and billing gates as the REST call endpoint. |
| `get_call`            | `call_id`                                   | Retrieves call status, summary, and grade.                                                    |
| `list_calls`          | optional `limit` (1–100), optional `status` | Lists recent calls.                                                                           |
| `get_call_transcript` | `call_id`                                   | Retrieves the complete transcript for a call.                                                 |

All tools are scoped to the organization bound to the API key. An id from
another organization behaves as unavailable.

## Protocol methods

The endpoint implements the MCP JSON-RPC methods needed for Streamable HTTP
clients:

* `initialize`
* `notifications/initialized`
* `tools/list`
* `tools/call`

You can inspect the tool catalog directly:

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/mcp \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'
```

Call a tool with its name and arguments:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_calls",
    "arguments": { "limit": 20, "status": "completed" }
  }
}
```

Tool results are MCP text-content items. Tool failures are returned in the
result with `isError: true`; unknown JSON-RPC methods return a protocol error.

## Placing calls safely

`place_call` follows the same rules as
[`POST /v1/call`](/api-reference/outbound-calls): the agent and number must
belong to the key's organization, the number must be eligible for outbound
calling, the organization must have sufficient balance, and any applicable
outbound-calling confirmation must be complete.

Treat a client with access to `place_call` as a production caller. Restrict who
can use the client, make the intended agent and number clear in its own prompt,
and review calls in Call History.

## Complete wire reference

See [MCP Servers API](/api-reference/mcp-servers#thunderphone-as-an-mcp-server)
for response examples, JSON-RPC errors, and the remote-server management API.