Open in

Use o ThunderPhone como um servidor MCP

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:

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

Esta é a direção oposta de conectar um servidor MCP remoto a um agente de voz:

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 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.

Alternativas de CLI e stdio

A CLI do ThunderPhone pode gravar a configuração do cliente preservando servidores não relacionados:

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 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)

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.
Selecione Conectar, inicie sessão no ThunderPhone, escolha a organização e aprove as permissões.
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

Se o ThunderPhone aparecer no diretório de aplicativos do ChatGPT, selecione-o e conecte-se.
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.
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.

Claude Code

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:

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

Cursor

Crie .cursor/mcp.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:

{
  "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:

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

{
  "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:

{
  "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.