# API de WhatsApp para agentes de IA: servidor MCP, llms.txt

URL: https://wa.genuka.com/es/docs/guides/ai-agents
Language: Spanish

> Conecta Claude, Cursor o VS Code a la API de WhatsApp Business con el servidor MCP de Genuka WA, además de llms.txt, documentación en Markdown y una especificación OpenAPI.

Para que un agente de IA trabaje con WhatsApp a través de Genuka WA, agrega el servidor MCP `@genuka/whatsapp-mcp`
a tu cliente con una clave API: Claude, Cursor o VS Code podrán entonces listar tus números, enviar
plantillas y lanzar campañas. Si lo que quieres es que un asistente escriba el código de la integración, apúntalo a
`/llms.txt`, a las páginas `.mdx` y a `/openapi.json`.

*Última actualización: 8 de octubre de 2026*

## ¿Qué puede hacer un agente de IA con Genuka WA?

Genuka WA es una API REST para la plataforma oficial WhatsApp Business Platform (la Cloud API de Meta). Genuka es un
Tech Provider de Meta: conectas tu propio número de WhatsApp Business mediante el Embedded Signup de Meta
y luego envías notificaciones, códigos de un solo uso y campañas por HTTP. Un agente puede usarla de dos maneras,
y la mayoría de los equipos terminan usando ambas:

| Quieres que el agente…                                                                                            | Usa                                                         | Lo que obtiene                                                                        |
| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Actúe sobre tu cuenta: enviar un mensaje, crear una plantilla, lanzar una campaña, revisar el estado de un número | El servidor MCP `@genuka/whatsapp-mcp`                      | 17 herramientas, cada una asociada a un endpoint de `/api/v1`                         |
| Escriba código en tu repositorio que llame a Genuka WA                                                            | `/llms.txt`, páginas `.mdx`, `/openapi.json`, `/pricing.md` | La documentación y el contrato de la API, en formatos que un modelo lee sin navegador |

[MCP](https://modelcontextprotocol.io/docs/getting-started/intro) es el estándar abierto que usan las aplicaciones
de IA para conectarse a herramientas externas; Claude, ChatGPT, VS Code y Cursor lo admiten.

## ¿Cómo instalo el servidor MCP de Genuka WA?

1. ### Crea una clave API

   En el panel, abre la [página de claves API](https://wa.genuka.com/dashboard/settings) y crea una
   clave (`pk_live_…`). Se muestra una sola vez. Si el agente solo trabaja para uno de tus negocios, elige ese
   negocio al crear la clave: el agente no podrá ver ni modificar los demás (consulta
   [Autenticación](https://wa.genuka.com/es/docs/authentication)).

   Necesitas Node.js 20 o posterior: el cliente inicia el servidor con `npx`.

2. ### Agrega el servidor a tu cliente

   **Claude Code**

   ```bash
   claude mcp add --env GENUKA_WA_API_KEY=pk_live_xxx --transport stdio genuka-wa -- npx -y @genuka/whatsapp-mcp
   ```

   Para compartirlo con tu equipo sin hacer commit de la clave, coloca este `.mcp.json` en la raíz del
   repositorio; Claude Code expande `${GENUKA_WA_API_KEY}` a partir del entorno de cada desarrollador:

   ```json title=".mcp.json"
   {
     "mcpServers": {
       "genuka-wa": {
         "command": "npx",
         "args": ["-y", "@genuka/whatsapp-mcp"],
         "env": { "GENUKA_WA_API_KEY": "${GENUKA_WA_API_KEY}" }
       }
     }
   }
   ```

   **Claude Desktop**

   **Settings → Developer → Edit Config** abre `claude_desktop_config.json`
   (`~/Library/Application Support/Claude/` en macOS, `%APPDATA%\Claude\` en Windows). Agrega el
   servidor, guarda, luego cierra y vuelve a abrir Claude Desktop.

   ```json title="claude_desktop_config.json"
   {
     "mcpServers": {
       "genuka-wa": {
         "command": "npx",
         "args": ["-y", "@genuka/whatsapp-mcp"],
         "env": { "GENUKA_WA_API_KEY": "pk_live_xxx" }
       }
     }
   }
   ```

   **Cursor**

   En `~/.cursor/mcp.json` (todos los proyectos) o `.cursor/mcp.json` (este proyecto). `${env:…}` lee la
   clave desde tu entorno:

   ```json title=".cursor/mcp.json"
   {
     "mcpServers": {
       "genuka-wa": {
         "command": "npx",
         "args": ["-y", "@genuka/whatsapp-mcp"],
         "env": { "GENUKA_WA_API_KEY": "${env:GENUKA_WA_API_KEY}" }
       }
     }
   }
   ```

   **VS Code**

   En `.vscode/mcp.json`, o mediante **MCP: Open User Configuration** para todos los espacios de trabajo. VS Code
   pide la clave una sola vez y no la guarda en el archivo:

   ```json title=".vscode/mcp.json"
   {
     "inputs": [
       { "type": "promptString", "id": "genuka-wa-api-key", "description": "Genuka WA API key", "password": true }
     ],
     "servers": {
       "genuka-wa": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "@genuka/whatsapp-mcp"],
         "env": { "GENUKA_WA_API_KEY": "${input:genuka-wa-api-key}" }
       }
     }
   }
   ```

   **Windsurf**

   Windsurf se llama Devin Desktop desde el 2 de junio de 2026. En el panel Cascade, abre el menú `…`
   y luego **Open MCP config file**:

   ```json title="mcp_config.json"
   {
     "mcpServers": {
       "genuka-wa": {
         "command": "npx",
         "args": ["-y", "@genuka/whatsapp-mcp"],
         "env": { "GENUKA_WA_API_KEY": "pk_live_xxx" }
       }
     }
   }
   ```

   `GENUKA_WA_BASE_URL` es opcional y su valor predeterminado es `https://wa.genuka.com`.

3. ### Verifica la conexión

   En Claude Code, `claude mcp list` o `/mcp` muestra el servidor como conectado. Luego pídele al agente
   "Lista mis números de WhatsApp": llama a `list_numbers`, que devuelve el `id` de cada número (el
   `connectionId` que necesitan todas las demás herramientas), su negocio y su calificación de calidad. Si la clave
   falta o es incorrecta, la herramienta responde con el motivo en lugar de fallar en silencio.

## ¿Qué herramientas expone el servidor MCP?

| Herramienta                                                    | Qué hace                                                                                  | ¿Envía o modifica algo?                                                                  |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `list_numbers`                                                 | Números conectados y su estado                                                            | No                                                                                       |
| `get_number_health`                                            | Calificación de calidad en tiempo real, nivel de límite de mensajes, rendimiento, alertas | No                                                                                       |
| `send_text_message`                                            | Texto libre, dentro de la ventana de 24 horas                                             | Envía un mensaje                                                                         |
| `send_template_message`                                        | Una plantilla aprobada: variables, encabezado, botones, código de un solo uso             | Envía un mensaje                                                                         |
| `send_media_message`                                           | Imagen, video, audio, documento o sticker                                                 | Envía un mensaje                                                                         |
| `list_templates` / `get_template`                              | Plantillas, su estado y el resultado de la revisión de Meta                               | No                                                                                       |
| `create_template`                                              | Envía una plantilla a revisión de Meta                                                    | Sí                                                                                       |
| `list_webhooks` / `create_webhook`                             | Endpoints de webhook; la creación devuelve el secreto de firma una sola vez               | La creación envía los eventos de tu cuenta, incluidos los mensajes de clientes, a la URL |
| `test_webhook`                                                 | Eventos de ejemplo firmados enviados a tu endpoint                                        | Llama a tu endpoint                                                                      |
| `list_campaigns` / `get_campaign` / `list_campaign_recipients` | Campañas y entrega por destinatario                                                       | No                                                                                       |
| `create_campaign`                                              | Un borrador: una plantilla, un número, una lista de destinatarios                         | Sí, no envía nada                                                                        |
| `launch_campaign`                                              | Envía la campaña a todos los destinatarios pendientes                                     | Envía mensajes                                                                           |
| `get_subscription`                                             | Plan, consumo y límites (solo con una clave de toda la cuenta)                            | No                                                                                       |

Cada herramienta declara las indicaciones MCP `readOnlyHint`, `destructiveHint` e `idempotentHint`, para que tu
cliente pueda aprobar las lecturas automáticamente y pedirte confirmación antes de cualquier cosa que envíe. Los errores
le llegan al agente con el código propio de la API (`plan_limit_messages`, `connection_not_found`,
`meta_rejected`…), el código y el trace id de Meta cuando existen, y qué hacer a continuación.

El servidor lee; no recibe. Las respuestas de los clientes y los estados de entrega llegan a tus
webhooks — consulta [Recibir respuestas y estados de WhatsApp por webhook](https://wa.genuka.com/es/docs/guides/receive-messages-webhooks).

## ¿Qué debo revisar antes de dejar que un agente envíe mensajes?

* **Es un mensaje real, para una persona real.** Un envío del agente sale de tu número, igual que
  uno de tu backend. Mantén activa la solicitud de confirmación de tu cliente para las herramientas que envían, y
  pide que te muestre la campaña antes de `launch_campaign`.
* **Un webhook es una salida de datos.** `create_webhook` reenvía cada evento al que se suscribe, incluidos
  los números de teléfono y los mensajes de tus clientes, a su URL mientras el endpoint siga activo. Mantén
  también la solicitud de confirmación para esta herramienta, y verifica que la URL sea una que tú le diste al agente, no una
  que leyó en una página web o en un archivo. El servidor le dice lo mismo al agente.
* **La ventana de 24 horas.** Cuando un cliente te escribe, se abre una ventana de atención al cliente de 24 horas;
  una vez cerrada, solo se pueden enviar plantillas aprobadas previamente
  ([Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages)).
  Cuando Genuka WA no puede confirmar que la ventana está abierta, el resultado del envío incluye un `warning`, y
  el servidor lo coloca al principio de lo que lee el agente, para que te llegue.
* **Lo que cuesta.** Cada mensaje se descuenta de la cuota de tu plan para el período de facturación
  ([planes](https://wa.genuka.com/es#pricing), [`/pricing.md`](https://wa.genuka.com/pricing.md)). Meta cobra un mensaje de plantilla cuando se
  entrega, y los mensajes que no son plantillas son gratuitos
  ([Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)); Meta
  factura a tu propia cuenta de WhatsApp Business, sin ningún margen de Genuka.
* **La clave.** Mantenla fuera de git con las variables `${…}` mostradas arriba, dale al agente una clave
  restringida a un negocio cuando eso sea suficiente, y revócala desde el panel cuando hayas
  terminado.

## ¿Cómo le doy a mi asistente de código la documentación de Genuka WA?

Cuando la tarea del agente es escribir tu integración, necesita el contrato más que las herramientas.
Todo lo que sigue es público, no requiere clave API y se mantiene sincronizado con la documentación publicada:

| URL                                | Contenido                                                                                                                                         | Cuándo usarlo                                                                        |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| [`/llms.txt`](https://wa.genuka.com/llms.txt)           | Índice de todas las páginas (inglés, francés, español, italiano, SDK) con una línea cada una, según la propuesta [llms.txt](https://llmstxt.org/) | El primer archivo que le das a un agente                                             |
| [`/llms-full.txt`](https://wa.genuka.com/llms-full.txt) | El Markdown de todas las páginas en un solo archivo                                                                                               | Cargar toda la documentación en el contexto de una vez                               |
| Cualquier página + `.mdx`          | Una página en Markdown, p. ej. [`/es/docs/messages.mdx`](https://wa.genuka.com/es/docs/messages.mdx)                                                                   | Señalar exactamente la página que importa                                            |
| [`/openapi.json`](https://wa.genuka.com/openapi.json)   | Descripción OpenAPI 3.1 de `/api/v1`                                                                                                              | Generar un cliente tipado, o dejar que el agente verifique los nombres de los campos |
| [`/pricing.md`](https://wa.genuka.com/pricing.md)       | Planes, precios y límites en Markdown, generados a partir del catálogo de facturación                                                             | Responder "¿cuánto me va a costar?"                                                  |

```bash
curl https://wa.genuka.com/llms.txt
curl https://wa.genuka.com/es/docs/webhooks.mdx
```

## ¿Qué prompt le doy al asistente?

Nombra el producto, el framework y el evento, y deja que lea la documentación. Por ejemplo:

> Agrega notificaciones de WhatsApp de pedido enviado a mi app Next.js con Genuka WA. Lee primero
> [https://wa.genuka.com/llms.txt](https://wa.genuka.com/llms.txt).

Un buen resultado tiene tres partes: una plantilla `UTILITY` como `order_shipped`, enviada una sola vez y
aprobada por Meta; código del lado del servidor que llama a `POST /api/v1/messages` cuando se envía el pedido; y una
ruta de webhook que verifica `X-Genuka-Signature` antes de confiar en un estado. Con la plantilla `order_shipped`
de la [guía de notificaciones de pedidos](https://wa.genuka.com/es/docs/guides/order-notifications) (tres variables en el cuerpo
y un botón con enlace de seguimiento), la llamada se ve así. Los valores deben coincidir uno a uno con las
variables de la plantilla, o Meta rechaza el mensaje ([error 132000](https://wa.genuka.com/es/docs/errors/132000)):

**curl**

```bash
curl -X POST https://wa.genuka.com/api/v1/messages \
  -H "Authorization: Bearer $GENUKA_WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "con_1",
    "to": "+237690000001",
    "template": {
      "name": "order_shipped",
      "language": "en",
      "body": ["Awa", "ORD-1042", "DHL"],
      "buttons": [{ "type": "url", "text": "ORD-1042" }]
    }
  }'
```

**Node.js**

```ts title="lib/whatsapp.ts"
export async function notifyOrderShipped(phone: string, firstName: string, orderNumber: string, carrier: string) {
  const response = await fetch("https://wa.genuka.com/api/v1/messages", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      connectionId: process.env.GENUKA_WA_CONNECTION_ID,
      to: phone, // E.164: "+237690000001"
      template: {
        name: "order_shipped",
        language: "en",
        body: [firstName, orderNumber, carrier], // {{1}}, {{2}}, {{3}} en orden
        buttons: [{ type: "url", text: orderNumber }], // completa el enlace de seguimiento
      },
    }),
  });
  const result = await response.json();
  if (!response.ok) throw new Error(`${result.error}: ${result.message ?? ""}`);
  return result.data.messageId as string; // aceptado por Meta, aún no entregado
}
```

**Python**

```python title="whatsapp.py"
import os
import requests

def notify_order_shipped(phone: str, first_name: str, order_number: str, carrier: str) -> str:
    response = requests.post(
        "https://wa.genuka.com/api/v1/messages",
        headers={"Authorization": f"Bearer {os.environ['GENUKA_WA_API_KEY']}"},
        json={
            "connectionId": os.environ["GENUKA_WA_CONNECTION_ID"],
            "to": phone,  # E.164: "+237690000001"
            "template": {
                "name": "order_shipped",
                "language": "en",
                "body": [first_name, order_number, carrier],  # {{1}}, {{2}}, {{3}} en orden
                "buttons": [{"type": "url", "text": order_number}],  # completa el enlace de seguimiento
            },
        },
        timeout=30,
    )
    result = response.json()
    if not response.ok:
        raise RuntimeError(f"{result['error']}: {result.get('message', '')}")
    return result["data"]["messageId"]  # aceptado por Meta, aún no entregado
```

**PHP**

```php title="whatsapp.php"
<?php
function notifyOrderShipped(string $phone, string $firstName, string $orderNumber, string $carrier): string
{
    $ch = curl_init('https://wa.genuka.com/api/v1/messages');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('GENUKA_WA_API_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'connectionId' => getenv('GENUKA_WA_CONNECTION_ID'),
            'to' => $phone, // E.164: "+237690000001"
            'template' => [
                'name' => 'order_shipped',
                'language' => 'en',
                'body' => [$firstName, $orderNumber, $carrier], // {{1}}, {{2}}, {{3}} en orden
                'buttons' => [['type' => 'url', 'text' => $orderNumber]], // completa el enlace de seguimiento
            ],
        ]),
    ]);
    $result = json_decode(curl_exec($ch), true);
    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    if ($status >= 400) {
        throw new RuntimeException($result['error'] . ': ' . ($result['message'] ?? ''));
    }
    return $result['data']['messageId']; // aceptado por Meta, aún no entregado
}
```

El recorrido completo (plantilla, idempotencia, seguimiento de la entrega) está en
[Notificaciones de pedidos por WhatsApp desde tu backend](https://wa.genuka.com/es/docs/guides/order-notifications).

## ¿Qué debo poner en AGENTS.md?

`AGENTS.md`, `CLAUDE.md` o `.cursor/rules` los lee el asistente antes de cada tarea. Estas
líneas le evitan los errores que vemos con más frecuencia en las integraciones de WhatsApp. Están en
inglés, el idioma que estos archivos suelen compartir dentro de un equipo:

```md title="AGENTS.md"
## WhatsApp (Genuka WA)

- WhatsApp goes through the Genuka WA REST API: base URL https://wa.genuka.com/api/v1,
  header `Authorization: Bearer $GENUKA_WA_API_KEY`. Server-side only: never ship the key to a
  browser or a mobile app. We do not call Meta's Graph API directly.
- Docs for agents: https://wa.genuka.com/llms.txt; append `.mdx` to any docs URL for Markdown;
  API contract: https://wa.genuka.com/openapi.json.
- `connectionId` is the `id` returned by `GET /api/v1/connections`. It lives in config
  (`GENUKA_WA_CONNECTION_ID`), never hard-coded.
- Phone numbers are E.164: `+237690000001`.
- Business-initiated messages (order updates, reminders, codes) are templates. Free-form `text`
  is only delivered within 24 hours of the customer's last message.
- Templates are created once (`POST /api/v1/templates`) and reviewed by Meta; only `approved`
  ones can be sent. Use the template's exact `language`.
- A 200 from `POST /api/v1/messages` means Meta accepted the message, not that it was delivered.
  Delivery and replies arrive on webhooks; verify `X-Genuka-Signature` on the raw body first.
- Errors are `{ "error": "code", "message": "…" }`. Never retry `plan_limit_messages`; when the
  body has `meta.retryable: false`, change the request instead of retrying it.
```

## Preguntas frecuentes

### ¿El servidor MCP envía mensajes reales de WhatsApp?

Sí. `send_text_message`, `send_template_message`, `send_media_message` y `launch_campaign` envían
desde tu número conectado a destinatarios reales, y se descuentan de la cuota de tu plan. Las lecturas
(`list_*`, `get_*`) no modifican nada.

### ¿El servidor MCP es gratuito?

El paquete `@genuka/whatsapp-mcp` tiene licencia MIT y es gratuito. Usa tu cuenta de Genuka WA, facturada
como una suscripción por número de WhatsApp ([planes](https://wa.genuka.com/es#pricing)). Meta factura los mensajes de plantilla
entregados a tu propia cuenta de WhatsApp Business, sin ningún margen de Genuka.

### ¿Con qué clientes de IA funciona?

Con cualquier cliente MCP capaz de iniciar un servidor local (stdio): Claude Code, Claude Desktop, Cursor, VS Code
y Windsurf se cubren arriba. El servidor necesita Node.js 20 o posterior.

### ¿Puede el agente leer las respuestas de mis clientes?

No a través del servidor MCP: no tiene ninguna herramienta para los mensajes entrantes. Las respuestas y los estados de entrega se
envían a tu endpoint de webhook, que el agente puede crear con `create_webhook` (en una URL que tú
le indiques) y probar con `test_webhook`.

### ¿Cómo limito lo que el agente puede alcanzar?

Dale una clave restringida a un negocio. Las listas devuelven entonces solo las filas de ese negocio, cualquier otro
id responde `404` y `get_subscription` se rechaza — consulta [Autenticación](https://wa.genuka.com/es/docs/authentication).

## Fuentes

* [Meta — Send messages (customer service window)](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages)
* [Meta — Pricing on the WhatsApp Business Platform](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing)
* [Model Context Protocol — What is MCP?](https://modelcontextprotocol.io/docs/getting-started/intro)
* [The /llms.txt proposal](https://llmstxt.org/)
* [Claude Code — Connect Claude Code to tools via MCP](https://code.claude.com/docs/en/mcp)
* [MCP — Connect to local MCP servers (Claude Desktop)](https://modelcontextprotocol.io/docs/develop/connect-local-servers)
* [Cursor — Model Context Protocol](https://cursor.com/docs/context/mcp)
* [VS Code — MCP configuration reference](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration)
* [Devin Desktop (formerly Windsurf) — MCP](https://docs.devin.ai/desktop/cascade/mcp)
* [Devin Desktop FAQ — Windsurf becomes Devin Desktop](https://docs.devin.ai/desktop/devin-desktop-faq)
