---
title: "Usa ThunderPhone como servidor MCP"
description: "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:

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

Esta es la dirección opuesta a [conectar un servidor MCP remoto a un agente de voz](/es/guides/mcp-servers):

| Dirección | Resultado |
| --- | --- |
| Servidor MCP remoto → agente de ThunderPhone | Un agente de voz puede llamar las herramientas del servidor remoto. |
| ThunderPhone → tu cliente MCP | Tu agente de programación puede crear, probar y operar ThunderPhone. |

## Autenticación

Usa [OAuth](/es/guides/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.

<Warning>
  Una clave `sk_live_` puede leer datos de la organización y realizar acciones de producción, como desplegar agentes, realizar llamadas, comprar números, iniciar campañas y eliminar recursos. Mantenla fuera del código del navegador, repositorios, capturas de pantalla y registros de chat. Usa el almacén de secretos o la compatibilidad con variables de entorno de tu cliente y revoca de inmediato una clave expuesta.
</Warning>

## Alternativas de CLI y stdio

La [CLI de ThunderPhone](/es/guides/cli) puede escribir la configuración del cliente mientras conserva
los servidores no relacionados:

```bash
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](/es/guides/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](#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

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

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

### Cursor

Crea `.cursor/mcp.json`:

```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:

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

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

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

| Herramienta | Argumentos principales | Anotaciones | Qué hace |
| --- | --- | --- | --- |
| `get_connection_identity` | — | R, I | Valida la credencial y devuelve su organización y metadatos seguros de la credencial. |

### Agentes

| Herramienta | Argumentos principales | Anotaciones | Qué hace |
| --- | --- | --- | --- |
| `list_agents` | — | R, I | Lista agentes. |
| `get_agent` | `agent_id` | R, I | Obtiene un agente. |
| `create_agent` | configuración del agente | — | Crea un agente. |
| `update_agent` | `agent_id`, campos modificados | D | Prepara campos en el borrador del agente y reemplaza lo que tenía el borrador. Se ejecuta sin un paso de confirmación: el agente implementado no cambia hasta `deploy_agent`, y `discard_agent_draft` revierte el borrador. |
| `deploy_agent` | `agent_id`, `if_updated_at` opcional | D, I | Promueve el borrador a producción. |
| `discard_agent_draft` | `agent_id`, `if_updated_at` opcional, `confirmation_token` en la segunda solicitud | D, I | Descarta los cambios preparados. Dos pasos; consulta [Confirmación de acciones destructivas](#confirming-destructive-actions). |
| `duplicate_agent` | `agent_id`, `name` opcional | — | Copia un agente dentro de la organización. |
| `delete_agent` | `agent_id`, `confirmation_token` en la segunda solicitud | D, I | Elimina permanentemente un agente. Dos pasos. |
| `list_agent_versions` | `agent_id` | R, I | Lista las versiones de configuración implementadas. |

### Números telefónicos y operadores

| Herramienta | Argumentos principales | Anotaciones | Qué hace |
| --- | --- | --- | --- |
| `list_phone_numbers` | — | R, I | Lista los números y el enrutamiento de la organización. |
| `get_phone_number_limits` | — | R, I | Obtiene el uso y los límites de los números administrados. |
| `provision_phone_number` | `area_code`, `city`, `state`, `idempotency_key` opcionales | D, O | Compra un número entrante administrado por ThunderPhone. |
| `list_voip_connections` | — | R, I | Lista los operadores de quienes llaman conectados. |
| `search_voip_numbers` | `connection_id`, `country`, `type`, `area_code` opcional | R, I, O | Busca en el inventario del operador. |
| `import_voip_numbers` | `connection_id`, `numbers` | D, O | Importa números que ya pertenecen al operador. |
| `update_phone_number` | `phone_number_id`, campos de enrutamiento/etiqueta/webhook | D | Actualiza el enrutamiento del número, incluida la asignación del agente. |
| `delete_phone_number` | `phone_number_id`, `confirm`, `release_at_provider` opcional, `confirmation_token` en la segunda solicitud | D, I, O | Libera un número. Dos pasos. |

### SMS

| Herramienta | Argumentos principales | Anotaciones | Qué hace |
| --- | --- | --- | --- |
| `send_sms` | `from_number`, `to`, `body`, `idempotency_key` | D, I, O | Envía un SMS de texto sin formato mediante un número de Twilio o Telnyx conectado. |

### Llamadas

| Herramienta | Argumentos principales | Anotaciones | Qué hace |
| --- | --- | --- | --- |
| `list_calls` | filtros opcionales, `limit`, `offset` | R, I | Lista las llamadas con los filtros de historial de llamadas de REST. |
| `get_call` | `call_id` | R, I | Obtiene el estado y los metadatos de la llamada. |
| `get_call_transcript` | `call_id`, `live` opcional | R, I | Obtiene la transcripción de la llamada. |
| `get_call_audio_url` | `call_id`, `download` opcional | R, I, O | Devuelve una URL de audio firmada; nunca transmite audio a través de MCP. |
| `get_call_grade` | `call_id` | R, I | Obtiene la calificación más reciente de la llamada. |
| `place_call` | `agent_id`, `from_number`, `to_number` | D, O | Realiza una llamada saliente no idempotente. |
| `export_calls` | filtros de llamadas, `export_format` | R, I | Exporta hasta el límite del endpoint REST en formato JSON o CSV. |

### Pruebas y validación

| Herramienta | Argumentos principales | Anotaciones | Qué hace |
| --- | --- | --- | --- |
| `list_test_scenarios` | `agent_id` | R, I | Enumera los escenarios de prueba. |
| `create_test_scenario` | `agent_id`, `title`, `scenario_prompt`, condiciones opcionales | — | Crea un escenario. |
| `generate_test_scenarios` | `agent_id`, `count` opcional, `include_edge_cases`, `locale` | O | Genera escenarios a partir del prompt del agente. |
| `run_agent_tests` | `agent_id`, `channel`, `consent_to_charge`, selección/matriz opcional | D, O | Ejecuta escenarios mediante la web o telefonía. |
| `get_test_run` | `agent_id`, `batch_id` | R, I | Obtiene el estado del lote y los resultados por escenario. |
| `list_validation_runs` | `agent_id` | R, I | Enumera las ejecuciones recientes de validación de borradores. |
| `get_validation_status` | `agent_id` | R, I | Obtiene el estado de validación más reciente y la coincidencia del borrador. |

### Conocimiento

| Herramienta | Argumentos principales | Anotaciones | Qué hace |
| --- | --- | --- | --- |
| `list_knowledge_bases` | — | R, I | Lista bases de conocimiento. |
| `create_knowledge_base` | `name`, `description` opcional | — | Crea una base de conocimiento. |
| `add_knowledge_document` | `knowledge_base_id`, `name`, `content` | — | Agrega texto o Markdown. |
| `import_knowledge_url` | `url`, `name` opcional | O | Pone una página pública en cola para una ingesta segura. |
| `search_knowledge` | `knowledge_base_id`, `query` | R, I | Busca mediante la recuperación de producción. |

### Integraciones, webhooks y servidores MCP remotos

| Herramienta | Argumentos principales | Anotaciones | Qué hace |
| --- | --- | --- | --- |
| `list_integrations` | — | R, I | Enumera las integraciones de funciones HTTP. |
| `create_integration` | `display_name`, `spec` de función, campos de endpoint opcionales | — | Crea una herramienta HTTP. Agrega encabezados de autenticación en el dashboard. |
| `test_integration` | `url`, método/cuerpo/tiempo de espera opcionales, `integration_id` con `header_names`, `confirmation_token` en la segunda solicitud | D, O | Envía una solicitud de prueba limitada y protegida contra SSRF. Los valores de encabezados guardados se completan desde la integración y solo se envían a su propio host. `POST` (el valor predeterminado), `PUT`, `PATCH` y `DELETE` requieren dos pasos; `GET` se ejecuta de inmediato. |
| `list_webhook_endpoints` | — | R, I | Enumera los endpoints de webhook firmados. |
| `list_webhook_deliveries` | `agent_id` opcional, `endpoint_id` opcional | R, I | Enumera resultados recientes de entregas de webhook sin payload. |
| `create_webhook_endpoint` | `label`, `url`, eventos/estado opcionales | O | Crea un endpoint de webhook firmado. |
| `test_webhook_endpoint` | `endpoint_id` | O | Envía un evento sintético mediante la entrega normal. |
| `list_mcp_servers` | — | R, I | Enumera los servidores remotos que pueden llamar los agentes de voz. |
| `create_mcp_server` | `display_name`, `url` | O | Registra y sincroniza un servidor remoto. Los servidores que necesitan encabezados de autenticación se agregan en el dashboard. |
| `sync_mcp_server_tools` | `server_id` | D, O | Actualiza el catálogo de herramientas de un servidor remoto. |

### Campañas

| Herramienta | Argumentos principales | Anotaciones | Qué hace |
| --- | --- | --- | --- |
| `list_campaigns` | — | R, I | Lista campañas salientes. |
| `create_campaign` | campos de la campaña | — | Crea una campaña en borrador. |
| `add_campaign_contacts` | `campaign_id`, `contacts` | — | Agrega hasta 5,000 contactos JSON. |
| `campaign_action` | `campaign_id`, `action`, `consent_to_charge` opcional, `confirmation_token` en la segunda solicitud | D, O | Ejecuta `start`, `pause`, `resume` o `stop`. `start` y `resume` son de dos pasos; `pause` y `stop` se ejecutan de inmediato. |
| `get_campaign_stats` | `campaign_id` | R, I | Obtiene contadores y resultados recientes. |

### Voces, facturación y documentación

| Herramienta | Argumentos principales | Anotaciones | Qué hace |
| --- | --- | --- | --- |
| `list_voices` | — | R, I | Enumera las voces y los idiomas compatibles. |
| `preview_voice` | `voice`, `language`, `text` | O | Genera una muestra y devuelve una URL firmada. |
| `list_voice_clones` | — | R, I | Enumera los clones de voz personalizados. |
| `get_billing_summary` | — | R, I | Obtiene el saldo y los precios oficiales del nivel; no expone mutaciones de pago. |
| `search_docs` | `query`, opcional `limit` | R, I, O | Busca en el índice de documentación pública. |
| `get_doc_page` | `path` | R, I, O | Obtiene una página pública de documentación en Markdown. |

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:

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

| URI | Contenido |
| --- | --- |
| `thunderphone://docs/llms.txt` | Índice de documentación pública. |
| `thunderphone://docs/quickstart` | Markdown de inicio rápido. |
| `thunderphone://pricing` | Markdown de precios públicos actuales. |

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:

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