> ## Documentation Index
> Fetch the complete documentation index at: https://gowa-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Servidor MCP

> Permitir que los agentes de IA utilicen WhatsApp a través del protocolo integrado de contexto de modelos de GOWA en /mcp.

GOWA sirve un [Protocolo de Contexto del Modelo](https://modelcontextprotocol.io) endpoint del mismo proceso que la API REST. Cualquier cliente MCP que soporte el transporte **streamable HTTP** puede enviar mensajes, leer chats y administrar grupos a través de él.

* URL: `http://<host>:3000<APP_BASE_PATH>/mcp` (por defecto `http://localhost:3000/mcp`)
* Activado por defecto. Deshabilita con `MCP_ENABLED=false` o `--mcp-enabled=false`.
* Sin estado: no hay sacudidas de mano de sesión para mantener vivo entre llamadas.

> [!NOTE]
>
> ¿Vas a actualizar desde una versión anterior? El comando independiente `./whatsapp mcp` y su endpoint SSE en el puerto 8080 (`/sse`) ya no están disponibles. Ejecuta `./whatsapp rest` y configura los clientes para que apunten a `/mcp`. El antiguo conjunto de una herramienta por operación se ha sustituido por las herramientas consolidadas que se muestran a continuación.

## Conectar un cliente

`/mcp` se sienta detrás de la misma Auth Básica que la API REST. Envía la cabecera `Authorization`, más `X-Device-Id` si ejecutas más de un dispositivo:

```json theme={null}
{
  "mcpServers": {
    "whatsapp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Basic YWRtaW46Y2hhbmdlbWU=",
        "X-Device-Id": "my-device"
      }
    }
  }
}
```

`YWRtaW46Y2hhbmdlbWU=` es `base64("admin:changeme")`; genera el tuyo con `echo -n 'user:pass' | base64`. Omita `Authorization` si Basic Auth está apagado, y `X-Device-Id` si sólo hay un dispositivo.

El formato de configuración exacto depende del cliente. Si un cliente sólo puede lanzar servidores stdio, use un puente como `mcp-remote`.

## Herramientas

GOWA expone siete herramientas. Cada una acepta un argumento `type` (para enviar) o `action` (para todas las demás operaciones) que selecciona la operación.

| Herramienta | Valores `type` / `action` |
| - | - |
| `whatsapp_send` | `text`, `image`, `video`, `audio`, `document`, `sticker`, `location`, `contact`, `poll`, `link`, `forward` |
| `whatsapp_schedule` | `list`, `get`, `pause`, `resume`, `cancel` |
| `whatsapp_message` | `react`, `edit`, `revoke`, `delete`, `mark_read`, `mark_played`, `star`, `unstar`, `download_media` |
| `whatsapp_chat` | `list_chats`, `list_contacts`, `get_messages`, `archive` |
| `whatsapp_group` | `create`, `join_with_link`, `leave`, `info`, `participants`, `add_participants`, `remove_participants`, `promote`, `demote`, `invite_link`, `set_name`, `set_topic`, `set_settings`, `join_requests`, `manage_join_requests` |
| `whatsapp_app` | `status`, `login_qr`, `login_code`, `logout`, `reconnect` |
| `whatsapp_newsletter` | `follow`, `unfollow`, `info`, `directory`, `messages`, `message_updates`, `live_updates_subscribe`, `live_updates_unsubscribe`, `live_updates_list` |

Notas sobre argumentos:

* `whatsapp_send` siempre necesita `type` y `phone`. Los medios son enviados **sólo por URL** (`image_url`, `video_url`, `audio_url`, `file_url`, `sticker_url`); MCP no puede subir archivos locales. `link` necesita `link` y `caption`; `forward` necesita `message_id`.
* `whatsapp_send` acepta los [campos de programación](https://gowa-docs.mintlify.site/es/examples/scheduled-sends.md) (`scheduled_at`, `timezone`, `recurrence`, `weekdays`, `day_of_month`, `end_at`, `occurrence_limit`). Administra el resultado con `whatsapp_schedule` (`get`, `pause`, `resume` y `cancel` necesitan `schedule_id`).
* `whatsapp_message` necesita `phone` (el chat) y `message_id`; `edit` también necesita `message`.
* En GOWA `main` después de v9.9.0, `whatsapp_message` con `action: "edit"` acepta `media_type: "image"` o `media_type: "document"` para reemplazar un título. Coincide con el tipo de medio original y omite el `link`. Vea [Editar un subtítulo](https://gowa-docs.mintlify.site/es/examples/sending-messages.md#editar-una-imagen-o-t%C3%ADtulo-del-documento).
* `whatsapp_chat`: `get_messages` necesita `chat_jid`; `archive` necesita `chat_jid` y `archived`.
* `whatsapp_app`: `login_code` necesita `phone`.

Los botones experimentales, la solicitud de ubicación y los envíos de carrusel solo están disponibles a través de REST. Ver [mensajes interactivos](https://gowa-docs.mintlify.site/es/examples/interactive-messages.md). Herramientas de boletines de soporte para descubrimiento de canales, contadores de historial y suscripciones de actualización en vivo automáticamente renovadas. Ver [newsletters](https://gowa-docs.mintlify.site/es/examples/newsletters.md).

Las descargas de URL multimedia aplican las mismas comprobaciones de dirección pública que REST envía y conecta directamente sin `HTTP_PROXY` o `HTTPS_PROXY`. Las subidas desde archivos locales requieren la API REST.

Su cliente MCP muestra el esquema de entrada completo de cada herramienta. El endpoint HTTP acepta POST y DELETE. GET SSE streaming está deshabilitado.

## Selección de dispositivo

Cada llamada resuelve su dispositivo en este orden:

1. El argumento `device_id` en la llamada de herramienta.
2. La cabecera `X-Device-Id` en la conexión MCP.
3. El único dispositivo registrado, cuando existe exactamente.

De lo contrario, la llamada falla con `device identification required: set the X-Device-Id header or pass device_id`. Vea [Multi-device](https://gowa-docs.mintlify.site/es/concepts/multidevice.md).

## Clientes remotos con OAuth

Clientes alojados como Claude custom connectors no pueden conectar un encabezado Basic Auth. Para ellos, GOWA puede ejecutar un servidor de autorización OAuth 2.1 para `/mcp`. Está desactivado por defecto.

```env theme={null}
APP_BASIC_AUTH=admin:replace-with-a-strong-password
MCP_ENABLED=true
MCP_OAUTH_ENABLED=true
MCP_OAUTH_ISSUER_URL=https://gowa.example.com
# optional, defaults to issuer + APP_BASE_PATH + /mcp
MCP_OAUTH_RESOURCE_URL=https://gowa.example.com/mcp
```

Requisitos y comportamiento:

* Debe establecerse `APP_BASIC_AUTH`: la página de autorización firma a los usuarios con esas mismas cuentas. El inicio falla sin él.
* Emisor y recurso deben ser las URL **HTTPS** públicas que ven los clientes, no direcciones internas como `http://gowa:3000`.
* Con OAuth encendido, `/mcp` acepta un token Bearer **o** Basic Auth. No se aceptan fichas en rutas REST o UI.
* Los clientes se registran a sí mismos (RFC 7591 registro dinámico de clientes), los cuerpos de registro están limitados a 16 KiB y cada URI de redirección a 2 KiB. Los registros están limitados a 40 por hora y 1.000 clientes almacenados; los no utilizados se podan después de 24 horas.
* PKCE `S256` es obligatorio. Los códigos expiran después de 5 minutos, los tokens de acceso después de 1 hora; actualizan los tokens de rotación y reutilizan un antiguo revoca toda la familia de token. Solo se almacenan hash SHA-256 de tokens, en `MCP_OAUTH_DB_URI` (por defecto `file:storages/oauth.db`).

Las URIs de redirección deben coincidir exactamente con los valores registrados. Los clientes nativos pueden usar callbacks IP de bucle HTTP con un puerto dinámico. Las callbacks `localhost` requieren un puerto explícito y una coincidencia exacta. Otras redirecciones requieren HTTPS. El OAuth `resource` está vinculado a la URL canónica MCP; las peticiones de token pueden omitirlo, pero un valor proporcionado debe coincidir. Las respuestas de autorización exitosas incluyen `iss`.

Los códigos y tokens caducados son podados durante las escrituras de OAuth. Los hasacks rotados de refresco siguen siendo necesarios para detectar la repetición contra una familia en vivo, para como máximo una vida útil de 30 días más. La eliminación o sustitución de la base de datos OAuth invalida a los clientes y becas existentes.

Endpoints, en relación al emisor: `/oauth/authorize`, `/oauth/token`, `/oauth/register`. Discovery metadata uses path-insertion known URLs at the domain root so with `APP_BASE_PATH=/gowa` your proxy must route:

```text theme={null}
https://gowa.example.com/.well-known/oauth-authorization-server/gowa
https://gowa.example.com/.well-known/oauth-protected-resource/gowa/mcp
```

Comprobar descubrimiento desde fuera:

```bash theme={null}
curl -i -X POST https://gowa.example.com/mcp          # expect 401 with a Bearer challenge
curl https://gowa.example.com/.well-known/oauth-protected-resource/mcp
curl https://gowa.example.com/.well-known/oauth-authorization-server
```

Luego añade `https://gowa.example.com/mcp` como un conector personalizado e inicia sesión con una cuenta `APP_BASIC_AUTH`.

> [!WARNING]
>
> Asegúrate de que Cloudflare Access, desafíos de bot o proxies de autenticación delante de GOWA no intercepte las rutas bien conocidas, `/oauth/*` o `/mcp`. Fallo al iniciar sesión en `/oauth/authorize` en tu proxy.


## Related topics

- [Envíos programados](https://gowa-docs.mintlify.site/es/examples/scheduled-sends.md)
- [GOWA: WhatsApp REST API](https://gowa-docs.mintlify.site/es/index.md)
- [Referencia API](https://gowa-docs.mintlify.site/es/api-reference/introduction.md)
- [Referencia de configuración](https://gowa-docs.mintlify.site/es/configuration.md)
- [Autenticación de API](https://gowa-docs.mintlify.site/es/api-reference/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.