---
title: "Use o ThunderPhone como um servidor MCP"
description: "Crie, teste, valide e opere agentes de voz do ThunderPhone a partir do Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code ou outro cliente MCP HTTP transmissível."
---

O ThunderPhone disponibiliza um servidor HTTP com streaming do Model Context Protocol em:

```text
https://api.thunderphone.com/v1/mcp
```

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 | Um agente de voz pode chamar as ferramentas do servidor remoto. |
| ThunderPhone → seu cliente MCP | Seu agente de programação pode criar, testar e operar o ThunderPhone. |

## Autenticar

Use o [OAuth](/pt/guides/oauth) por padrão para clientes de diretório: faça login, escolha uma organização e aprove as permissões solicitadas. Revogue o acesso em **Organização → Chaves de API → Aplicativos autorizados**.

Para clientes configurados com uma chave de API, crie uma chave `sk_live_` em **Organização → Chaves** e exponha-a ao seu cliente MCP como `THUNDERPHONE_API_KEY`. A chave é vinculada a uma organização; um id pertencente a outra organização se comporta como se não fosse encontrado.

<Warning>
  Uma chave `sk_live_` pode ler dados da organização e executar ações de produção, como implantar agentes, realizar chamadas, comprar números, iniciar campanhas e excluir recursos. Mantenha-a fora de código de navegador, repositórios, capturas de tela e logs de chat. Use o armazenamento de segredos ou o suporte a variáveis de ambiente do seu cliente e revogue imediatamente uma chave exposta.
</Warning>

## Alternativas de CLI e stdio

A [CLI do ThunderPhone](/pt/guides/cli) pode gravar a configuração do cliente preservando
servidores não relacionados:

```bash
npx -y @thunderphone/mcp setup --client cursor --api-key-env THUNDERPHONE_API_KEY
npx thunderphone mcp setup --client claude-desktop --scope user
```

Após uma instalação global de `@thunderphone/mcp`, use `thunderphone-mcp setup` com as
mesmas opções. A configuração é compatível com Claude Code, Codex, Cursor, VS Code, Gemini, Claude
Desktop e Windsurf. HTTP direto é preferível; o Desktop usa stdio.

Para qualquer cliente compatível com stdio, configure `command: "npx"` com
`args: ["-y", "@thunderphone/mcp"]`. O wrapper usa primeiro `THUNDERPHONE_API_KEY`,
depois as credenciais de `thunderphone login`, renovando tokens expirados, e então
OAuth por meio de `mcp-remote`. O login por dispositivo e o OAuth exigem a disponibilização
correspondente de OAuth da API. O caminho com chave de API não exige isso. Configurações HTTP diretas não leem
o armazenamento de credenciais da CLI; use o wrapper stdio para reutilizar o login por dispositivo.

Estas são alternativas às configurações manuais de cliente abaixo.

## Configuração do cliente

Claude e ChatGPT usam [OAuth](/pt/guides/oauth) para iniciar sessão; nenhuma chave de API é usada. Se você ainda não tiver uma conta do ThunderPhone, escolha **Criar conta** na página de início de sessão e você retornará à tela de aprovação após verificar seu e-mail.

### Claude (web, desktop e mobile)

1. Abra **Personalizar → Conectores** (**Configurações → Conectores** em versões mais antigas). Se o ThunderPhone aparecer no diretório de conectores, selecione-o. Caso contrário, escolha **Adicionar conector personalizado**, nomeie-o como `ThunderPhone` e insira `https://api.thunderphone.com/v1/mcp`.
2. Selecione **Conectar**, inicie sessão no ThunderPhone, escolha a organização e aprove as permissões.
3. Em um chat, habilite o ThunderPhone no menu de ferramentas e peça o que precisar, por exemplo, "Liste meus agentes".

O Claude pede confirmação antes de usar cada ferramenta pela primeira vez. Para ignorar a maioria dessas solicitações, abra **Personalizar → Conectores → ThunderPhone** e defina **Ferramentas somente de leitura** como sempre permitidas. Essas ferramentas apenas consultam informações: agentes, chamadas, transcrições, saldos e documentação. Mantenha **Ferramentas de gravação/exclusão** com aprovação se quiser ver cada alteração antes que ela aconteça.

Conectores personalizados exigem um plano pago do Claude. Nos planos Team e Enterprise, um proprietário primeiro adiciona o conector nas configurações de conectores da organização; depois, cada membro conecta sua própria conta do ThunderPhone.

### ChatGPT

1. Se o ThunderPhone aparecer no diretório de aplicativos do ChatGPT, selecione-o e conecte-se.
2. Caso contrário, abra **Configurações → Aplicativos e conectores → Configurações avançadas**, ative o **Modo desenvolvedor** e crie um conector com a URL `https://api.thunderphone.com/v1/mcp` e autenticação OAuth.
3. Inicie sessão no ThunderPhone, escolha a organização e aprove as permissões. Adicione o ThunderPhone a um chat pelo menu de ferramentas.

Excluir um agente ou número de telefone, descartar um rascunho, iniciar uma campanha e enviar uma solicitação de teste que possa gravar em um sistema externo exigem uma segunda confirmação em qualquer um dos aplicativos; consulte [Confirmar ações destrutivas](#confirming-destructive-actions).

### Claude Code

```bash
claude mcp add --transport http thunderphone https://api.thunderphone.com/v1/mcp \
  --header "Authorization: Bearer $THUNDERPHONE_API_KEY"
```

### Codex

Adicione isto a `~/.codex/config.toml`:

```toml
[mcp_servers.thunderphone]
url = "https://api.thunderphone.com/v1/mcp"
bearer_token_env_var = "THUNDERPHONE_API_KEY"
```

### Cursor

Crie `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "thunderphone": {
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:THUNDERPHONE_API_KEY}"
      }
    }
  }
}
```

### Claude Desktop

Adicione uma ponte `mcp-remote` à configuração do Claude Desktop:

```json
{
  "mcpServers": {
    "thunderphone": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.thunderphone.com/v1/mcp",
        "--header",
        "Authorization: Bearer ${THUNDERPHONE_API_KEY}"
      ],
      "env": {
        "THUNDERPHONE_API_KEY": "sk_live_YOUR_API_KEY"
      }
    }
  }
}
```

### VS Code

Crie `.vscode/mcp.json` e insira a chave pelo prompt de entrada do VS Code:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "thunderphone-api-key",
      "description": "ThunderPhone organization API key",
      "password": true
    }
  ],
  "servers": {
    "thunderphone": {
      "type": "http",
      "url": "https://api.thunderphone.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${input:thunderphone-api-key}"
      }
    }
  }
}
```

## Ferramentas

Todas as ferramentas incluem anotações MCP. Nas tabelas, **R** significa somente leitura, **D** destrutiva, **I** idempotente e **O** interação com ambiente externo/rede. Um travessão indica que nenhuma indicação está definida.

### Conexão

| Ferramenta | Argumentos principais | Anotações | O que faz |
| --- | --- | --- | --- |
| `get_connection_identity` | — | R, I | Valida a credencial e retorna a organização e os metadados seguros da credencial. |

### Agentes

| Ferramenta | Argumentos principais | Anotações | O que faz |
| --- | --- | --- | --- |
| `list_agents` | — | R, I | Lista agentes. |
| `get_agent` | `agent_id` | R, I | Obtém um agente. |
| `create_agent` | configuração do agente | — | Cria um agente. |
| `update_agent` | `agent_id`, campos alterados | D | Prepara campos no rascunho do agente, substituindo o que havia no rascunho. É executada sem uma etapa de confirmação: o agente implantado permanece inalterado até `deploy_agent`, e `discard_agent_draft` reverte o rascunho. |
| `deploy_agent` | `agent_id`, `if_updated_at` opcional | D, I | Promove o rascunho para produção. |
| `discard_agent_draft` | `agent_id`, `if_updated_at` opcional, `confirmation_token` na segunda solicitação | D, I | Descarta alterações preparadas. Em duas etapas; consulte [Confirmação de ações destrutivas](#confirming-destructive-actions). |
| `duplicate_agent` | `agent_id`, `name` opcional | — | Copia um agente dentro da organização. |
| `delete_agent` | `agent_id`, `confirmation_token` na segunda solicitação | D, I | Exclui permanentemente um agente. Em duas etapas. |
| `list_agent_versions` | `agent_id` | R, I | Lista versões de configuração implantadas. |

### Números de telefone e operadoras

| Ferramenta | Principais argumentos | Anotações | O que faz |
| --- | --- | --- | --- |
| `list_phone_numbers` | — | R, I | Lista os números e o roteamento da organização. |
| `get_phone_number_limits` | — | R, I | Obtém o uso e os limites de números gerenciados. |
| `provision_phone_number` | `area_code`, `city`, `state`, `idempotency_key` opcionais | D, O | Compra um número de entrada gerenciado pelo ThunderPhone. |
| `list_voip_connections` | — | R, I | Lista as operadoras conectadas do cliente. |
| `search_voip_numbers` | `connection_id`, `country`, `type`, `area_code` opcional | R, I, O | Pesquisa o inventário da operadora. |
| `import_voip_numbers` | `connection_id`, `numbers` | D, O | Importa números já pertencentes à operadora. |
| `update_phone_number` | `phone_number_id`, campos de roteamento/rótulo/webhook | D | Atualiza o roteamento do número, incluindo a atribuição ao agente. |
| `delete_phone_number` | `phone_number_id`, `confirm`, `release_at_provider` opcional, `confirmation_token` na segunda solicitação | D, I, O | Libera um número. Em duas etapas. |

### SMS

| Ferramenta | Principais argumentos | Anotações | O que faz |
| --- | --- | --- | --- |
| `send_sms` | `from_number`, `to`, `body`, `idempotency_key` | D, I, O | Envia um SMS de texto simples por meio de um número Twilio ou Telnyx conectado. |

### Chamadas

| Ferramenta | Argumentos principais | Anotações | O que faz |
| --- | --- | --- | --- |
| `list_calls` | filtros opcionais, `limit`, `offset` | R, I | Lista chamadas com os filtros de histórico de chamadas da REST. |
| `get_call` | `call_id` | R, I | Obtém o status e os metadados da chamada. |
| `get_call_transcript` | `call_id`, `live` opcional | R, I | Obtém a transcrição da chamada. |
| `get_call_audio_url` | `call_id`, `download` opcional | R, I, O | Retorna uma URL de áudio assinada; nunca transmite áudio pelo MCP. |
| `get_call_grade` | `call_id` | R, I | Obtém a avaliação mais recente da chamada. |
| `place_call` | `agent_id`, `from_number`, `to_number` | D, O | Faz uma chamada de saída não idempotente. |
| `export_calls` | filtros de chamadas, `export_format` | R, I | Exporta até o limite do endpoint REST como JSON ou CSV. |

### Testes e validação

| Ferramenta | Principais argumentos | Anotações | O que faz |
| --- | --- | --- | --- |
| `list_test_scenarios` | `agent_id` | R, I | Lista cenários de teste. |
| `create_test_scenario` | `agent_id`, `title`, `scenario_prompt`, condições opcionais | — | Cria um cenário. |
| `generate_test_scenarios` | `agent_id`, `count` opcional, `include_edge_cases`, `locale` | O | Gera cenários a partir do prompt do agente. |
| `run_agent_tests` | `agent_id`, `channel`, `consent_to_charge`, seleção/matriz opcional | D, O | Executa cenários pela web ou telefonia. |
| `get_test_run` | `agent_id`, `batch_id` | R, I | Obtém o status do lote e os resultados por cenário. |
| `list_validation_runs` | `agent_id` | R, I | Lista execuções recentes de validação de rascunho. |
| `get_validation_status` | `agent_id` | R, I | Obtém o estado mais recente da validação e a correspondência do rascunho. |

### Conhecimento

| Ferramenta | Argumentos principais | Anotações | O que faz |
| --- | --- | --- | --- |
| `list_knowledge_bases` | — | R, I | Lista bases de conhecimento. |
| `create_knowledge_base` | `name`, `description` opcional | — | Cria uma base de conhecimento. |
| `add_knowledge_document` | `knowledge_base_id`, `name`, `content` | — | Adiciona texto ou Markdown. |
| `import_knowledge_url` | `url`, `name` opcional | O | Enfileira uma página pública para ingestão segura. |
| `search_knowledge` | `knowledge_base_id`, `query` | R, I | Pesquisa na recuperação em produção. |

### Integrações, webhooks e servidores MCP remotos

| Ferramenta | Argumentos principais | Anotações | O que faz |
| --- | --- | --- | --- |
| `list_integrations` | — | R, I | Lista integrações de funções HTTP. |
| `create_integration` | `display_name`, `spec` da função, campos opcionais do endpoint | — | Cria uma ferramenta HTTP. Adicione cabeçalhos de autenticação no painel. |
| `test_integration` | `url`, método/corpo/tempo limite opcionais, `integration_id` com `header_names`, `confirmation_token` na segunda solicitação | D, O | Envia uma solicitação de teste limitada e protegida contra SSRF. Os valores de cabeçalho salvos são preenchidos pela integração e enviados apenas ao seu próprio host. `POST` (o padrão), `PUT`, `PATCH` e `DELETE` ocorrem em duas etapas; `GET` é executado imediatamente. |
| `list_webhook_endpoints` | — | R, I | Lista endpoints de webhook assinados. |
| `list_webhook_deliveries` | `agent_id` opcional, `endpoint_id` opcional | R, I | Lista resultados recentes de entregas de webhook sem payload. |
| `create_webhook_endpoint` | `label`, `url`, eventos/status opcionais | O | Cria um endpoint de webhook assinado. |
| `test_webhook_endpoint` | `endpoint_id` | O | Envia um evento sintético pelo fluxo normal de entrega. |
| `list_mcp_servers` | — | R, I | Lista servidores remotos que podem ser chamados por agentes de voz. |
| `create_mcp_server` | `display_name`, `url` | O | Registra e sincroniza um servidor remoto. Servidores que exigem cabeçalhos de autenticação são adicionados no painel. |
| `sync_mcp_server_tools` | `server_id` | D, O | Atualiza o catálogo de ferramentas de um servidor remoto. |

### Campanhas

| Ferramenta | Argumentos principais | Anotações | O que faz |
| --- | --- | --- | --- |
| `list_campaigns` | — | R, I | Lista campanhas de saída. |
| `create_campaign` | campos da campanha | — | Cria uma campanha em rascunho. |
| `add_campaign_contacts` | `campaign_id`, `contacts` | — | Adiciona até 5.000 contatos JSON. |
| `campaign_action` | `campaign_id`, `action`, `consent_to_charge` opcional, `confirmation_token` na segunda solicitação | D, O | Executa `start`, `pause`, `resume` ou `stop`. `start` e `resume` são em duas etapas; `pause` e `stop` são executados imediatamente. |
| `get_campaign_stats` | `campaign_id` | R, I | Obtém contadores e resultados recentes. |

### Vozes, faturamento e documentação

| Ferramenta | Argumentos principais | Anotações | O que faz |
| --- | --- | --- | --- |
| `list_voices` | — | R, I | Lista vozes e idiomas compatíveis. |
| `preview_voice` | `voice`, `language`, `text` | O | Gera uma amostra e retorna uma URL assinada. |
| `list_voice_clones` | — | R, I | Lista clones de voz personalizados. |
| `get_billing_summary` | — | R, I | Obtém o saldo e os preços oficiais do nível; não expõe alterações de pagamento. |
| `search_docs` | `query`, `limit` opcional | R, I, O | Pesquisa o índice da documentação pública. |
| `get_doc_page` | `path` | R, I, O | Busca uma página pública de documentação em Markdown. |

Todas as ferramentas de produto usam os mesmos caminhos de código REST da API pública. Portanto, a validação REST, o escopo da organização, as funções, a autorização de faturamento, as cotas, a confirmação TCPA, a segurança do provedor e o comportamento de auditoria são aplicados sem alterações.

## Confirmação de ações destrutivas

Ferramentas marcadas com D alteram ou removem algo, ou começam a ligar para pessoas reais. As que não podem ser desfeitas exigem duas solicitações. A primeira solicitação não altera nada e retorna:

```json
{
  "status": "confirmation_required",
  "action": "Delete agent",
  "target": { "id": 195, "name": "Front Desk Receptionist" },
  "confirmation_token": "…",
  "expires_in_seconds": 600,
  "next_step": "…"
}
```

O assistente mostra à pessoa usuária o que será afetado e pede uma confirmação. Em seguida, repete a solicitação com os mesmos argumentos mais `confirmation_token`. Um token é válido por 10 minutos e abrange uma organização, uma ferramenta e um conjunto exato de argumentos; portanto, excluir três agentes exige três confirmações. `campaign_action` com `pause` ou `stop` ignora esta etapa para que uma campanha em execução possa sempre ser interrompida imediatamente, assim como `test_integration` com `GET`. Algumas ferramentas D são executadas em uma solicitação porque o D indica seu efeito, e não uma confirmação do lado do servidor: `update_agent` substitui o que estava no rascunho (`discard_agent_draft` o reverte), `deploy_agent` substitui a configuração ativa, `update_phone_number` redireciona chamadas ativas, `sync_mcp_server_tools` substitui o catálogo de ferramentas de um servidor remoto, `import_voip_numbers` redireciona números para sua operadora, `run_agent_tests` pode consumir crédito, `send_sms` e `place_call` entram em contato com uma pessoa real (`place_call` mantém sua própria confirmação de consentimento), e `provision_phone_number` compra um número. Seu cliente MCP ainda pode pedir que você as aprove.

## Prompts iniciais

`prompts/list` disponibiliza cinco fluxos de trabalho reutilizáveis:

- `create_inbound_receptionist`
- `run_agent_tests`
- `buy_and_attach_number`
- `review_low_grade_calls`
- `add_url_to_agent_knowledge`

Use `prompts/get` com o nome do prompt listado e os argumentos declarados para receber uma mensagem de usuário pronta para executar.

## Recursos

`resources/list` expõe referências públicas armazenadas em cache:

| URI | Conteúdo |
| --- | --- |
| `thunderphone://docs/llms.txt` | Índice da documentação pública. |
| `thunderphone://docs/quickstart` | Markdown de início rápido. |
| `thunderphone://pricing` | Markdown dos preços públicos atuais. |

Leia um recurso com `resources/read`. As buscas públicas usam um tempo limite curto, um limite de 2 MiB e um cache no processo de dez minutos.

## Protocolo e erros

O servidor oferece suporte às versões de protocolo `2025-06-18` e `2025-03-26`; ele retorna uma versão de cliente compatível e, caso contrário, seleciona `2025-06-18`. Ele implementa `initialize`, `ping`, ferramentas, prompts, recursos e notificações. As notificações retornam `202 Accepted`. Este servidor sem estado não expõe um ouvinte SSE nem exclusão de sessão; portanto, `GET` e `DELETE` retornam `405 Method Not Allowed` com `Allow: POST`.

Falhas de ferramentas continuam sendo respostas JSON-RPC bem-sucedidas com `isError: true`. Seu texto contém uma frase curta seguida por um bloco JSON:

```json
{
  "code": "insufficient_balance",
  "detail": "There is not enough prepaid balance.",
  "next_step": "Call get_billing_summary, add funds in Organization > Billing, then retry."
}
```

O prefixo distinto `outbound_tcpa_confirmation_required:` é mantido para `place_call`. Métodos JSON-RPC desconhecidos retornam `-32601` em uma resposta HTTP `200`. Lotes JSON-RPC não são compatíveis com MCP `2025-06-18` e retornam um erro de solicitação inválida `-32600` claro.