> ## 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 o ThunderPhone como um servidor MCP

> Conecte qualquer cliente MCP HTTP com streaming ao ThunderPhone para listar agentes, inspecionar chamadas e transcrições e fazer chamadas de saída com uma chave de API da organização.

O ThunderPhone expõe um servidor do Model Context Protocol em:

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

Aponte um cliente MCP para esse endpoint HTTP transmitível para disponibilizar os
agentes e as chamadas da sua organização como ferramentas. Esta é a direção oposta de
[conectar um servidor MCP remoto a um agente de voz](/pt/guides/mcp-servers):

| Direção                                      | Resultado                                                                           |
| -------------------------------------------- | ----------------------------------------------------------------------------------- |
| Servidor MCP remoto → agente do ThunderPhone | Seu agente de voz pode chamar as ferramentas do servidor remoto.                    |
| ThunderPhone → seu cliente MCP               | Seu cliente MCP pode chamar as ferramentas do ThunderPhone para agentes e chamadas. |

## Autenticação

Crie uma chave `sk_live_` em **Organização → Chaves** e envie-a como um token
Bearer. O endpoint MCP aceita chaves de API da organização, não cookies de sessão
do painel nem chaves publicáveis de widget.

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

<Warning>
  Uma chave `sk_live_` pode acessar dados da organização e realizar chamadas. Não a inclua em
  código de navegador, repositórios, capturas de tela ou registros de chat. Use um armazenamento de segredos
  compatível com seu cliente MCP e revogue uma chave imediatamente se ela for exposta.
</Warning>

## Ferramentas disponíveis

| Ferramenta            | Argumentos                                  | O que faz                                                                                                   |
| --------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `list_agents`         | nenhum                                      | Lista os agentes da organização com id, nome, produto e voz.                                                |
| `get_agent`           | `agent_id`                                  | Recupera um agente.                                                                                         |
| `place_call`          | `agent_id`, `from_number`, `to_number`      | Realiza uma chamada de saída com as mesmas validações e controles de cobrança do endpoint REST de chamadas. |
| `get_call`            | `call_id`                                   | Recupera o status, o resumo e a avaliação da chamada.                                                       |
| `list_calls`          | `limit` opcional (1–100), `status` opcional | Lista chamadas recentes.                                                                                    |
| `get_call_transcript` | `call_id`                                   | Recupera a transcrição completa de uma chamada.                                                             |

Todas as ferramentas são restritas à organização vinculada à chave de API. Um id de
outra organização é tratado como indisponível.

## Métodos do protocolo

O endpoint implementa os métodos MCP JSON-RPC necessários para clientes HTTP
transmitíveis:

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

Você pode inspecionar o catálogo de ferramentas diretamente:

```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": {}
  }'
```

Chame uma ferramenta com seu nome e argumentos:

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

Os resultados das ferramentas são itens de conteúdo de texto MCP. Falhas de ferramentas são retornadas
no resultado com `isError: true`; métodos JSON-RPC desconhecidos retornam um erro de protocolo.

## Como realizar chamadas com segurança

`place_call` segue as mesmas regras de
[`POST /v1/call`](/api-reference/outbound-calls): o agente e o número devem
pertencer à organização da chave, o número deve ser elegível para
chamadas de saída, a organização deve ter saldo suficiente e qualquer
confirmação aplicável para chamadas de saída deve estar concluída.

Trate um cliente com acesso a `place_call` como alguém que realiza chamadas em produção. Restrinja quem
pode usar o cliente, deixe claros o agente e o número pretendidos no próprio prompt
e revise as chamadas no Histórico de chamadas.

## Referência completa de integração

Consulte [API de servidores MCP](/api-reference/mcp-servers#thunderphone-as-an-mcp-server)
para exemplos de resposta, erros JSON-RPC e a API de gerenciamento de servidores remotos.