Conexión vía MCP

El servidor MCP de RyzeAPI expone la plataforma como herramientas que un cliente de IA puede llamar directamente, vía Model Context Protocol. En lugar de escribir tú las llamadas HTTP, el modelo (Claude, por ejemplo) usa 85 tools para enviar mensajes, gestionar instancias, grupos, chats, webhooks, Chatwoot y más.

85 tools

Cubren los 11 módulos de la API, desde el envío de mensajes hasta la administración de instancias.

Streamable HTTP

El transporte HTTP estándar del MCP, sin instalación local: solo apunta tu cliente a la URL.

Multi-tenant

Un servidor atiende a varios clientes; cada sesión está aislada y usa su propio token.

Sin credenciales almacenadas

El servidor no guarda ningún token. Envías el tuyo en cada sesión, mediante los headers.

Endpoint y transporte


Endpoint	`https://ryzeapi.cloud/mcp`
Transporte	Streamable HTTP (`POST` / `GET` / `DELETE` en `/mcp`)
Liveness	`GET /healthz` (sin autenticación)

Autenticación

La autenticación es por sesión: cada cliente envía su propio token de RyzeAPI en los headers al iniciar la sesión. Son los mismos tokens de la API REST.

Header	Obligatorio	Descripción
`token`	✅	Tu token de RyzeAPI (TokenAccount o TokenInstance). `Authorization: Bearer <token>` también funciona.
`instance`	,	Instancia por defecto de la sesión. Cada tool puede sobrescribirla con el argumento `instance`.

Usa TokenAccount si quieres operar varias instancias en la misma sesión (cada tool indica la instance). Usa TokenInstance + el header instance si vas a trabajar con una sola instancia. Consulta Autenticación para la diferencia entre ambos tokens.

Configura tu cliente

Claude Code (CLI)
Archivo de configuración (JSON)
Probar con curl

Añade el servidor con transporte HTTP y pasa tu token en el header:

claude mcp add --transport http ryzeapi https://ryzeapi.cloud/mcp \
  --header "token: TU_TOKEN_RYZEAPI"

Para fijar una instancia por defecto, añade otro header:

claude mcp add --transport http ryzeapi https://ryzeapi.cloud/mcp \
  --header "token: TU_TOKEN_RYZEAPI" \
  --header "instance: miInstancia"

Para Claude Desktop y otros clientes que usan un archivo de configuración de servidores MCP:

{
  "mcpServers": {
    "ryzeapi": {
      "type": "http",
      "url": "https://ryzeapi.cloud/mcp",
      "headers": {
        "token": "TU_TOKEN_RYZEAPI",
        "instance": "miInstancia"
      }
    }
  }
}

El campo instance es opcional.

Para confirmar que el endpoint está activo y tu token es aceptado, inicializa una sesión MCP:

curl -X POST "https://ryzeapi.cloud/mcp" \
  -H "token: TU_TOKEN_RYZEAPI" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "curl", "version": "1.0" }
    }
  }'

Trata el token como una credencial. Prefiere variables de entorno o el almacén de secretos de tu cliente, nunca dejes el token fijo en repositorios ni en el frontend.

Primera llamada: `whoami`

Tras conectar, pídele a tu cliente que llame a la tool whoami. Confirma que el token es válido y muestra la instancia por defecto de la sesión, es la forma más rápida de validar la conexión antes de cualquier operación.

Las 85 tools

Las herramientas siguen la convención recurso_acción (p. ej. tag_create, message_forward), con la familia send_* para todo lo que envía un nuevo mensaje o llamada. Cada tool lleva anotaciones que permiten al cliente pedir confirmación en acciones sensibles:

🟢 Solo lectura

Consultas que no cambian nada (whoami, instance_list, contact_list).

🟡 Escritura

Crean o modifican datos (send_text, group_create, webhook_set).

🔴 Destructivo

Eliminan recursos (instance_delete, chat_delete, message_delete).

Los 11 módulos corresponden 1:1 con las secciones de la Referencia de la API. Los argumentos de cada tool usan los mismos nombres de campo que la API REST, así que la documentación de cada endpoint aplica también a la tool equivalente:

Módulo	Tools	Referencia
Salud	2	Observabilidad
Instancias	13	Instancia
Mensajes	14	Mensajes
Llamadas	2	Llamadas
Chat	25	Chat
Grupos	9	Grupos
Comunidades	4	Comunidades
Newsletter	5	Newsletter
Perfil	4	Perfil
Eventos / Webhooks	4	Eventos
Chatwoot	3	Chatwoot

Próximos pasos

Autenticación

Entiende TokenAccount vs TokenInstance, los mismos tokens que usa el MCP.

Conceptos

Instancias, JIDs y los conceptos que manipulan las tools.

Referencia de la API

El detalle de cada endpoint, equivalente a cada tool del MCP.

Eventos

Recibe mensajes en tiempo real vía webhook o WebSocket.

85 tools

Streamable HTTP

Multi-tenant

Sin credenciales almacenadas

​Endpoint y transporte

​Autenticación

​Configura tu cliente

​Primera llamada: whoami

​Las 85 tools

🟢 Solo lectura

🟡 Escritura

🔴 Destructivo

​Próximos pasos

Autenticación

Conceptos

Referencia de la API

Eventos

Endpoint y transporte

Autenticación

Configura tu cliente

Primera llamada: `whoami`

Las 85 tools

Próximos pasos