Usa ThunderPhone como servidor MCP

Crea, prueba, valida y opera agentes de voz de ThunderPhone desde Claude, ChatGPT, Claude Code, Codex, Cursor, VS Code u otro cliente MCP de HTTP transmitible.

ThunderPhone expone un servidor HTTP transmitible de Model Context Protocol en:

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

Esta es la dirección opuesta a conectar un servidor MCP remoto a un agente de voz:

Autenticación#

Usa OAuth de forma predeterminada para clientes de directorio: inicia sesión, elige una organización y aprueba los permisos solicitados. Revoca el acceso en Organización → Claves de API → Aplicaciones autorizadas.

Para clientes configurados con una clave de API, crea una clave sk_live_ en Organización → Claves y exponla a tu cliente MCP como THUNDERPHONE_API_KEY. La clave está vinculada a una organización; un id perteneciente a otra organización se comporta como si no se encontrara.

Alternativas de CLI y stdio#

La CLI de ThunderPhone puede escribir la configuración del cliente mientras conserva los servidores no relacionados:

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

Después de una instalación global de @thunderphone/mcp, usa thunderphone-mcp setup con las mismas opciones. La configuración es compatible con Claude Code, Codex, Cursor, VS Code, Gemini, Claude Desktop y Windsurf. Se prefiere HTTP directo; Desktop usa stdio.

Para cualquier cliente compatible con stdio, configura command: "npx" con args: ["-y", "@thunderphone/mcp"]. El envoltorio usa primero THUNDERPHONE_API_KEY, luego las credenciales de thunderphone login, renovando los tokens vencidos, y después OAuth mediante mcp-remote. El inicio de sesión mediante dispositivo y OAuth requieren el despliegue correspondiente de OAuth de la API. La ruta de clave de API no lo requiere. Las configuraciones de HTTP directo no leen el almacén de credenciales de la CLI; usa el envoltorio stdio para reutilizar el inicio de sesión mediante dispositivo.

Estas son alternativas a las configuraciones manuales del cliente que se muestran a continuación.

Configuración del cliente#

Claude y ChatGPT inician sesión con OAuth; no se requiere una clave API. Si aún no tienes una cuenta de ThunderPhone, selecciona Crear cuenta en la página de inicio de sesión y regresarás a la pantalla de autorización después de verificar tu correo electrónico.

Claude (web, escritorio y móvil)#

1. Abre Personalizar → Conectores (Configuración → Conectores en versiones anteriores). Si ThunderPhone aparece en el directorio de conectores, selecciónalo. De lo contrario, elige Agregar conector personalizado, asígnale el nombre ThunderPhone e ingresa https://api.thunderphone.com/v1/mcp.
2. Selecciona Conectar, inicia sesión en ThunderPhone, elige la organización y aprueba los permisos.
3. En un chat, habilita ThunderPhone desde el menú de herramientas y pide lo que necesites, por ejemplo, "Enumera mis agentes".

Claude solicita confirmación antes de usar cada herramienta por primera vez. Para omitir la mayoría de esas solicitudes, abre Personalizar → Conectores → ThunderPhone y configura Herramientas de solo lectura para permitirlas siempre. Estas herramientas solo consultan información: agentes, llamadas, transcripciones, saldos y documentación. Deja Herramientas de escritura/eliminación con aprobación si quieres ver cada cambio antes de que ocurra.

Los conectores personalizados requieren un plan de pago de Claude. En los planes Team y Enterprise, un propietario primero agrega el conector en la configuración de conectores de la organización y luego cada miembro conecta su propia cuenta de ThunderPhone.

ChatGPT#

1. Si ThunderPhone aparece en el directorio de aplicaciones de ChatGPT, selecciónalo y conéctalo.
2. De lo contrario, abre Configuración → Aplicaciones y conectores → Configuración avanzada, activa Modo desarrollador y crea un conector con la URL https://api.thunderphone.com/v1/mcp y autenticación OAuth.
3. Inicia sesión en ThunderPhone, elige la organización y aprueba los permisos. Agrega ThunderPhone a un chat desde el menú de herramientas.

Eliminar un agente o número de teléfono, descartar un borrador, lanzar una campaña y enviar una solicitud de prueba que pueda escribir en un sistema externo requieren una segunda confirmación en cualquiera de las dos aplicaciones; consulta Confirmar acciones destructivas.

Claude Code#

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

Codex#

Agrega esto a ~/.codex/config.toml:

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

Cursor#

Crea .cursor/mcp.json:

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

Claude Desktop#

Agrega un puente mcp-remote a la configuración de 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#

Crea .vscode/mcp.json e ingresa la clave mediante la solicitud de entrada de 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}"
      }
    }
  }
}

Herramientas#

Cada herramienta incluye anotaciones MCP. En las tablas, R significa solo lectura, D destructiva, I idempotente y O interacción de red/mundo abierto. Un guion significa que no se estableció ninguna indicación.

Conexión#

Agentes#

Números telefónicos y operadores#

SMS#

Llamadas#

Pruebas y validación#

Conocimiento#

Integraciones, webhooks y servidores MCP remotos#

Campañas#

Voces, facturación y documentación#

Todas las herramientas del producto usan las mismas rutas de código REST que la API pública. Por lo tanto, la validación REST, el alcance de organización, los roles, la autorización de facturación, las cuotas, la confirmación TCPA, la seguridad del proveedor y el comportamiento de auditoría se aplican sin cambios.

Confirmación de acciones destructivas#

Las herramientas marcadas con D cambian o eliminan algo, o comienzan a llamar a personas reales. Las que no se pueden deshacer requieren dos solicitudes. La primera solicitud no cambia nada y devuelve:

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

El asistente muestra al usuario qué se verá afectado y le pide una confirmación. Luego repite la solicitud con los mismos argumentos más confirmation_token. Un token es válido durante 10 minutos y cubre una organización, una herramienta y un conjunto exacto de argumentos, por lo que eliminar tres agentes requiere tres confirmaciones. campaign_action con pause o stop omite este paso para que una campaña en curso siempre pueda detenerse de inmediato, al igual que test_integration con GET. Algunas herramientas D se ejecutan en una sola solicitud porque la D indica su efecto, no una confirmación del lado del servidor: update_agent reemplaza lo que tenía el borrador (discard_agent_draft lo revierte), deploy_agent reemplaza la configuración activa, update_phone_number redirige las llamadas activas, sync_mcp_server_tools reemplaza el catálogo de herramientas de un servidor remoto, import_voip_numbers vuelve a dirigir los números a tu operador, run_agent_tests puede consumir crédito, send_sms y place_call contactan a una persona real (place_call mantiene su propia confirmación de consentimiento), y provision_phone_number compra un número. Tu cliente MCP aún puede pedirte que las apruebes.

Prompts iniciales#

prompts/list anuncia cinco flujos de trabajo reutilizables:

• create_inbound_receptionist
• run_agent_tests
• buy_and_attach_number
• review_low_grade_calls
• add_url_to_agent_knowledge

Usa prompts/get con el nombre del prompt indicado y sus argumentos declarados para recibir un mensaje de usuario listo para ejecutar.

Recursos#

resources/list expone referencias públicas almacenadas en caché:

Lee uno con resources/read. Las consultas públicas usan un tiempo de espera corto, un límite de 2 MiB y una caché en proceso de diez minutos.

Protocolo y errores#

El servidor admite las versiones de protocolo 2025-06-18 y 2025-03-26; devuelve la versión de cliente admitida y, de lo contrario, selecciona 2025-06-18. Implementa initialize, ping, herramientas, prompts, recursos y notificaciones. Las notificaciones devuelven 202 Accepted. Este servidor sin estado no expone un listener SSE ni eliminación de sesiones, por lo que GET y DELETE devuelven 405 Method Not Allowed con Allow: POST.

Los fallos de las herramientas siguen siendo respuestas JSON-RPC exitosas con isError: true. Su texto contiene una frase corta seguida de un bloque JSON:

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

El prefijo distintivo outbound_tcpa_confirmation_required: se conserva para place_call. Los métodos JSON-RPC desconocidos devuelven -32601 en una respuesta HTTP 200. Los lotes JSON-RPC no son compatibles con MCP 2025-06-18 y devuelven un error limpio de solicitud no válida -32600.