# Servidor MCP para asistentes IA

> Conecta Claude, Cursor, VS Code, ChatGPT, Gemini CLI o Codex CLI a tu espacio de WhatSetter con 66 herramientas MCP, una sola clave API y sin código.

Source: https://docs.whatsetter.com/es/developers/mcp/

**MCP** (Model Context Protocol) es el estándar abierto que permite a un asistente IA usar un software a través de herramientas. El servidor MCP de WhatSetter expone **66 herramientas**, una por endpoint de la API, para que tu asistente lea tus leads y tus conversaciones de Instagram y Messenger, importe contactos, bloquee un prefijo, o explique por qué un agente dijo algo y corrija su prompt, todo desde un chat.

## El servidor

| Elemento | Valor |
|---|---|
| URL | `https://mcp.whatsetter.com/mcp` |
| Transporte | Streamable HTTP. `https://mcp.whatsetter.com/sse` sigue funcionando para clientes más antiguos. |
| Autenticación | OAuth (recomendado) o una cabecera directa `Authorization: Bearer ws_live_…` |
| Qué necesita | Una clave API creada en **Configuración**, luego **API y MCP** |

El servidor es un simple traductor: cada llamada a una herramienta es una llamada a la API REST con tu clave. Los scopes, los límites de peticiones y las [reglas anti-ban](/es/dashboard/anti-ban/) se aplican exactamente igual que en la API.

## Dos formas de autenticarse

**OAuth.** Añades la URL del servidor en tu cliente. El cliente abre una página de consentimiento de WhatSetter en tu navegador; pegas tu clave `ws_live_…` una sola vez y haces clic en **Authorize**. El cliente guarda entonces un token revocable y nunca vuelve a ver la clave. Úsalo con Claude, ChatGPT, Cursor, VS Code y cualquier cliente compatible con OAuth.

**Bearer directo.** Pasas la clave tú mismo, en una cabecera `Authorization: Bearer ws_live_…`. Úsalo en scripts, servidores y clientes donde prefieras gestionar el secreto en una variable de entorno.

```
POST https://mcp.whatsetter.com/mcp
Authorization: Bearer ws_live_…
```

En ambos casos, revocar la clave en el dashboard corta la conexión en menos de un minuto.

## Claude Code

Añade el servidor y luego ejecuta `/mcp` dentro de Claude Code para abrir la página de consentimiento:

```bash
claude mcp add --transport http whatsetter https://mcp.whatsetter.com/mcp
```

Para usar la clave directamente en lugar de OAuth:

```bash
claude mcp add --transport http whatsetter https://mcp.whatsetter.com/mcp \
  --header "Authorization: Bearer ws_live_…"
```

Añade `--scope user` para que el servidor esté disponible en todos tus proyectos en lugar de solo en el actual.

## Claude (web y aplicación de escritorio)

Los conectores personalizados se configuran en tu cuenta de Claude y luego están disponibles en la aplicación web y en la aplicación de escritorio de Claude.

1. Abre **Customize**, luego **Connectors**.
2. Haz clic en **+**, luego **Add custom connector**.
3. Pega `https://mcp.whatsetter.com/mcp` como URL del servidor MCP remoto y haz clic en **Add**.
4. Se abre una página de WhatSetter: pega tu clave API y haz clic en **Authorize**.

## Cursor

Haz clic en el enlace de instalación, o añade el servidor a mano en `~/.cursor/mcp.json`. Cursor abre la página de consentimiento en el primer uso.

<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=whatsetter&config=eyJ1cmwiOiJodHRwczovL21jcC53aGF0c2V0dGVyLmNvbS9tY3AifQ==">Añadir WhatSetter a Cursor</a>

```json
{
  "mcpServers": {
    "whatsetter": {
      "url": "https://mcp.whatsetter.com/mcp"
    }
  }
}
```

Para usar la clave directamente, añade un objeto `headers` con `"Authorization": "Bearer ws_live_…"` a la misma entrada.

## VS Code

Desde la línea de comandos, o en `.vscode/mcp.json` (o en tu perfil de usuario con **MCP: Open User Configuration**). VS Code ejecuta el flujo OAuth en tu navegador en la primera conexión.

```bash
code --add-mcp '{"name":"whatsetter","type":"http","url":"https://mcp.whatsetter.com/mcp"}'
```

```json
{
  "servers": {
    "whatsetter": {
      "type": "http",
      "url": "https://mcp.whatsetter.com/mcp"
    }
  }
}
```

## ChatGPT

Los servidores MCP remotos están disponibles para cuentas Pro, Plus, Business, Enterprise y Education en la web, tras activar el modo desarrollador.

1. Abre **Settings**, luego **Security and login**, y activa **Developer mode**.
2. Ve a `chatgpt.com/plugins` y selecciona el botón más para crear una app para tu servidor MCP.
3. Dale un nombre y, bajo **Connection**, introduce `https://mcp.whatsetter.com/mcp` como URL del servidor MCP.
4. Elige OAuth como autenticación y completa la página de consentimiento de WhatSetter.

En una conversación, elige **Developer mode** en el menú más y selecciona WhatSetter.

## Gemini CLI

Gemini CLI descubre el flujo OAuth por sí solo para servidores HTTP remotos:

```bash
gemini mcp add --transport http whatsetter https://mcp.whatsetter.com/mcp
```

Para usar la clave directamente:

```bash
gemini mcp add --transport http --header "Authorization: Bearer ws_live_…" whatsetter https://mcp.whatsetter.com/mcp
```

## Codex CLI

Con la clave en una variable de entorno:

```bash
export WHATSETTER_API_KEY="ws_live_…"
codex mcp add whatsetter --url https://mcp.whatsetter.com/mcp --bearer-token-env-var WHATSETTER_API_KEY
```

O con OAuth:

```bash
codex mcp add whatsetter --url https://mcp.whatsetter.com/mcp
codex mcp login whatsetter
```

El equivalente en `~/.codex/config.toml`:

```toml
[mcp_servers.whatsetter]
url = "https://mcp.whatsetter.com/mcp"
bearer_token_env_var = "WHATSETTER_API_KEY"
```

## Las 66 herramientas

Cada herramienta necesita el scope del endpoint al que llama. Una clave sin ese scope hace que la herramienta responda `insufficient_scope`.

| Herramienta | Scope | Qué hace |
|---|---|---|
| `whoami` | ninguno | Espacio, nombre de la clave y scopes concedidos. Llámala primero. |
| `list_leads` | `leads:read` | Listar leads, filtrables por estado, campaña, canal, teléfono, tu `external_reference`, origen, enlace rastreado, fecha. |
| `get_lead` | `leads:read` | Un lead con estado, etiquetas, responsable, siguiente acción, contadores. |
| `update_lead` | `leads:write` | Cambiar estado, etiquetas, `assigned_to`, `next_action_at`, `next_action_label`, `deal_status`, `lost_reason`. |
| `handoff_lead` | `leads:write` | Detener la IA en esta conversación y pasarla a un humano. |
| `resume_lead` | `leads:write` | Devolver la conversación a la IA. |
| `list_lead_notes` | `leads:read` | Notas de un lead, las más recientes primero. |
| `add_lead_note` | `leads:write` | Añadir una nota a un lead. |
| `list_conversations` | `conversations:read` | Bandeja de entrada en WhatsApp, Instagram y Messenger, actividad más reciente primero: quién responde cada una, cuáles esperan respuesta, qué leyó la clasificación. Filtros `channel`, `needs_reply`, `triage`. |
| `get_conversation_messages` | `conversations:read` | Historial completo de mensajes de un lead. |
| `send_message` | `messages:send` | **Envía un mensaje real** a un lead que ya está en conversación, en su canal. WhatsApp: reglas anti-ban. Instagram y Messenger: solo en las 24 horas que siguen al último mensaje de la persona. Se aplica una `Idempotency-Key` automática. |
| `send_whatsapp_message` | `messages:send` | La misma herramienta que `send_message`, con su primer nombre. |
| `list_lists` | `lists:read` | Tus listas de contactos. |
| `create_list` | `lists:write` | Crear una lista vacía. Con `keep_open`, una lista terminada vuelve a arrancar sola cuando llegan contactos. |
| `import_leads` | `lists:write` | Subir hasta 500 contactos a una lista. La importación no envía ningún mensaje por sí misma. |
| `list_campaigns` | `campaigns:read` | Campañas con su estado, sus canales y su número conectado. |
| `pause_campaign` | `campaigns:write` | Pausar una campaña activa. |
| `resume_campaign` | `campaigns:write` | Reanudar una campaña en pausa. Los envíos se reanudan. |
| `add_campaign_lead` | `messages:send` | **Envía el primer mensaje** a un lead opt-in por el pipeline de la campaña. |
| `list_bookings` | `bookings:read` | Reuniones agendadas por el agente. |
| `list_groups` | `groups:read` | Grupos de WhatsApp rastreados. |
| `get_group` | `groups:read` | Un grupo con sus contadores, enlace de invitación y modo de IA. |
| `list_group_members` | `groups:read` | Miembros de un grupo, activos o que se fueron. |
| `list_group_messages` | `groups:read` | Transcripción de un grupo. |
| `list_group_events` | `groups:read` | Entradas y salidas de un grupo. |
| `list_webhooks` | `webhooks:manage` | Tus suscripciones, sin los secretos. |
| `create_webhook` | `webhooks:manage` | Suscribir un endpoint HTTPS. El secreto se devuelve una sola vez. |
| `delete_webhook` | `webhooks:manage` | Borrar una suscripción. |
| `test_webhook` | `webhooks:manage` | Enviar un evento de prueba firmado a tu endpoint. |
| `list_blocked_contacts` | `blocklist:manage` | Números y prefijos bloqueados. |
| `block_contact` | `blocklist:manage` | Bloquear un número o un prefijo. El agente deja de responderle. |
| `unblock_contact` | `blocklist:manage` | Quitar un bloqueo. |
| `list_team_members` | `team:read` | Miembros del espacio, para asignar leads. |
| `list_links` | `links:read` | Enlaces rastreados con su número de clics. |
| `get_link` | `links:read` | Un enlace con sus estadísticas de 30 días. |
| `get_agent_prompts` | `prompts:read` | Todo con lo que trabaja un agente: sus prompts, lo que está en línea, sus variables y su base de conocimientos. |
| `get_agent_prompt` | `prompts:read` | Un texto de un agente. |
| `update_agent_prompt` | `prompts:write` | **Cambia un prompt, en línea desde el próximo mensaje del agente.** Versión nueva para la conversación y el primer mensaje. Rechazado mientras un borrador guardado en el dashboard espera, hasta que elijas qué hacer con él. |
| `list_prompt_versions` | `prompts:read` | El historial de un prompt, con estado y autor. |
| `get_prompt_version` | `prompts:read` | Una versión con su texto completo. |
| `compare_prompt_versions` | `prompts:read` | Lo que una versión cambia respecto a otra, o al texto en servicio, en forma de diff. |
| `restore_prompt_version` | `prompts:write` | **Vuelve a poner en servicio una versión anterior**, en línea desde el próximo mensaje. |
| `list_knowledge_bases` | `knowledge:read` | Las bases de conocimientos con sus fuentes y sus agentes vinculados. |
| `get_knowledge_base` | `knowledge:read` | Una base con cada sitio, cada archivo (y si su texto se puede editar) y su número de respuestas. |
| `search_knowledge` | `knowledge:read` | Los pasajes que el agente recibe para un mensaje. La misma búsqueda que al responder. |
| `list_knowledge_answers` | `knowledge:read` | Los pares de pregunta y respuesta de una base. |
| `add_knowledge_answer` | `knowledge:write` | Añadir una respuesta. Los agentes la usan desde su próxima respuesta. |
| `update_knowledge_answer` | `knowledge:write` | Corregir una respuesta. El texto anterior no se guarda. |
| `delete_knowledge_answer` | `knowledge:write` | Quitar una respuesta. |
| `get_knowledge_file` | `knowledge:read` | Todo el texto de un archivo. Para un PDF o un archivo Word, el texto que el agente tiene. |
| `add_knowledge_file` | `knowledge:write` | Añadir un archivo de texto. Se lee enseguida. |
| `update_knowledge_file` | `knowledge:write` | Reescribir un archivo de texto: un solo lugar con reemplazos precisos, o todo el texto. Los agentes lo saben desde su próxima respuesta. |
| `delete_knowledge_file` | `knowledge:write` | Quitar un archivo de cualquier tipo. |
| `list_instagram_accounts` | `instagram:read` | Las cuentas de Instagram conectadas: lo que puede hacer cada una, su página de Facebook, su agente, su clasificación, la pausa tras la respuesta de una persona. |
| `list_instagram_posts` | `instagram:read` | Las publicaciones de Instagram de los últimos 7, 30 o 90 días: las vistas frente a la media de la cuenta, y lo que trajeron, hasta las citas reservadas. |
| `get_instagram_best_times` | `instagram:read` | Los días y las horas en que las publicaciones de la cuenta funcionan mejor, y los tres próximos momentos para publicar. |
| `get_instagram_stats` | `instagram:read` | Lo que hicieron las automatizaciones en 7, 30 o 90 días frente al periodo anterior, por día, por automatización y por publicación. |
| `list_scheduled_instagram_posts` | `instagram:read` | Las publicaciones programadas desde WhatSetter, su estado y el motivo de un fallo. |
| `get_scheduled_instagram_post` | `instagram:read` | Una publicación programada: su estado, su enlace una vez publicada, su copia en la página de Facebook. |
| `schedule_instagram_post` | `instagram:write` | **Publica públicamente en Instagram**, ahora o a una hora: una foto, un carrusel, un reel (o un reel de prueba) o una historia, con un primer comentario y una automatización opcionales. |
| `update_scheduled_instagram_post` | `instagram:write` | **Puede publicar**: cambiar la descripción, la hora, el primer comentario, la automatización o las opciones de una publicación programada; `publish_at: null` la publica en un minuto. |
| `cancel_scheduled_instagram_post` | `instagram:write` | Cancelar una publicación programada. No sale. |
| `list_instagram_automations` | `instagram:read` | Las automatizaciones de comentarios, historias y mensajes, con lo que hicieron. |
| `create_instagram_automation` | `instagram:write` | Crear una automatización, apagada por defecto. **Encendida, escribe a personas reales.** |
| `update_instagram_automation` | `instagram:write` | Cambiar una automatización, o encenderla y apagarla. |
| `delete_instagram_automation` | `instagram:write` | Borrar una automatización y sus contadores. |

Cinco herramientas pueden llegar a una persona real: `send_message` (y su primer nombre `send_whatsapp_message`) y `add_campaign_lead` envían un mensaje, y `create_instagram_automation` / `update_instagram_automation` encienden una automatización que escribe a todas las personas que comentan sus palabras. Tres publican o retiran en Instagram: `schedule_instagram_post`, `update_scheduled_instagram_post` y `cancel_scheduled_instagram_post`. `resume_campaign` reanuda los envíos propios de una campaña. `test_webhook` envía a tu servidor, no a un contacto.

Dos herramientas cambian lo que dice un agente en servicio desde su próximo mensaje: `update_agent_prompt` y `restore_prompt_version`.

## Explicar y corregir una respuesta

Pregunta al asistente por qué un agente dijo algo. Lee tres cosas seguidas y cita lo que explica la respuesta:

| Paso | Herramienta | Qué da |
|---|---|---|
| 1 | `get_conversation_messages` | El intercambio. Cada mensaje dice qué lo escribió: el primer mensaje, una respuesta, un seguimiento o una persona. |
| 2 | `get_agent_prompts` | El prompt con el que trabajaba el agente, con los valores de sus variables. |
| 3 | `search_knowledge` | Los pasajes que el agente recibió de su base de conocimientos para ese mensaje. |

Luego pide la corrección. El asistente propone el cambio más pequeño, te lo muestra, y lo aplica con `update_agent_prompt`, `add_knowledge_answer` o `update_knowledge_file` cuando estás de acuerdo. `restore_prompt_version` deshace un cambio de prompt, y `compare_prompt_versions` muestra qué cambió entre dos versiones.

Si un borrador guardado en el dashboard espera en el prompt, el asistente te lo dice antes de cambiar nada: el agente no lee ese borrador, y tú eliges de qué texto partir.

El servidor envía estos pasos al asistente cuando se conecta, así que no tienes que detallarlos. El detalle está en [Prompts de los agentes](/es/developers/guides/prompts/) y [Bases de conocimientos](/es/developers/guides/knowledge/).

## Ejemplos de peticiones

- «Muéstrame los leads calificados esta semana y quién es responsable de cada uno.»
- «Asigna todos los leads calificados sin responsable a Julia y pon una siguiente acción el lunes a las 9 llamada Devolver llamada.»
- «Bloquea el prefijo +91, motivo: fuera de mercado.»
- «¿Qué enlace rastreado trajo más leads en los últimos 30 días?»
- «Importa estos 40 contactos a una lista nueva llamada Webinar septiembre.» (pega los contactos)
- «Pausa la campaña Acme España.»
- «Resume la conversación con +34612345678 y añade una nota con el resumen.»
- «¿Qué mensajes de Instagram esperan una respuesta mía? Prepara una respuesta para cada uno, las reviso antes de que envíes.»
- «Crea una automatización, apagada, que envíe la guía del comprador a todos los que comenten GUIA en mis próximas publicaciones.»
- «¿Por qué mi agente Julien le dijo a +34612345678 que la prueba cuesta 12 euros? Encuentra la causa y propón una corrección.»
- «En el prompt de conversación de Julien, añade una regla: nunca dar un precio antes de que el lead diga qué necesita. Muéstrame el cambio primero.»

## Seguridad

- Las herramientas de lectura están marcadas como solo lectura. `send_message`, `send_whatsapp_message`, `add_campaign_lead`, las herramientas de automatización de Instagram y las que publican están marcadas como de efecto real: un cliente bien diseñado **te pregunta antes de llamarlas**. Lee el mensaje antes de aprobarlo, va a una persona real.
- `update_agent_prompt` y `restore_prompt_version` están marcadas del mismo modo: el cambio está en línea desde el próximo mensaje del agente, así que léelo antes de aprobar. Cada cambio de prompt es una versión nueva, y una restauración trae de vuelta la anterior.
- El asistente solo puede hacer lo que la clave permite. Dale a un asistente una clave **Personalizado** con scopes de lectura si no debe enviar nada.
- Cada sesión `/mcp` está ligada a la clave que la abrió: un id de sesión robado es inútil sin la clave.
- **Revoca la clave** en **Configuración**, luego **API y MCP**, y todo se detiene: llamadas REST, sesiones OAuth y sesiones bearer directas por igual.

## Relacionado

- [Autenticación y permisos](/es/developers/authentication/)
- [Errores, límites e idempotencia](/es/developers/errors/)
- [Usar estos docs con asistentes IA](/es/developers/ai-assistants/)
