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

# Conexión vía MCP

> Conecta clientes de IA (Claude y otros) a RyzeAPI mediante el servidor MCP, con 85 tools listas para usar

El **servidor MCP de RyzeAPI** expone la plataforma como herramientas que un cliente de IA puede llamar directamente, vía [Model Context Protocol](https://modelcontextprotocol.io). 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.

<CardGroup cols={2}>
  <Card title="85 tools" icon="screwdriver-wrench">
    Cubren los 11 módulos de la API, desde el envío de mensajes hasta la administración de instancias.
  </Card>

  <Card title="Streamable HTTP" icon="plug">
    El transporte HTTP estándar del MCP, sin instalación local: solo apunta tu cliente a la URL.
  </Card>

  <Card title="Multi-tenant" icon="users">
    Un servidor atiende a varios clientes; cada sesión está aislada y usa su propio token.
  </Card>

  <Card title="Sin credenciales almacenadas" icon="shield-check">
    El servidor no guarda ningún token. Envías el tuyo en cada sesión, mediante los headers.
  </Card>
</CardGroup>

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

<Tip>
  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](/es/guide/authentication) para la diferencia entre ambos tokens.
</Tip>

## Configura tu cliente

<Tabs>
  <Tab title="Claude Code (CLI)">
    Añade el servidor con transporte HTTP y pasa tu token en el header:

    ```bash theme={null}
    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:

    ```bash theme={null}
    claude mcp add --transport http ryzeapi https://ryzeapi.cloud/mcp \
      --header "token: TU_TOKEN_RYZEAPI" \
      --header "instance: miInstancia"
    ```
  </Tab>

  <Tab title="Archivo de configuración (JSON)">
    Para Claude Desktop y otros clientes que usan un archivo de configuración de servidores MCP:

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

    El campo `instance` es opcional.
  </Tab>

  <Tab title="Probar con curl">
    Para confirmar que el endpoint está activo y tu token es aceptado, inicializa una sesión MCP:

    ```bash theme={null}
    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" }
        }
      }'
    ```
  </Tab>
</Tabs>

<Warning>
  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.
</Warning>

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

<CardGroup cols={3}>
  <Card title="🟢 Solo lectura" icon="eye">
    Consultas que no cambian nada (`whoami`, `instance_list`, `contact_list`).
  </Card>

  <Card title="🟡 Escritura" icon="pen">
    Crean o modifican datos (`send_text`, `group_create`, `webhook_set`).
  </Card>

  <Card title="🔴 Destructivo" icon="trash">
    Eliminan recursos (`instance_delete`, `chat_delete`, `message_delete`).
  </Card>
</CardGroup>

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](/es/api/observability/overview) |
| Instancias         |   13  | [Instancia](/es/api/instance/overview)           |
| Mensajes           |   14  | [Mensajes](/es/api/messages/overview)            |
| Llamadas           |   2   | [Llamadas](/es/api/calls/fake)                   |
| Chat               |   25  | [Chat](/es/api/chat/overview)                    |
| Grupos             |   9   | [Grupos](/es/api/groups/overview)                |
| Comunidades        |   4   | [Comunidades](/es/api/communities/overview)      |
| Newsletter         |   5   | [Newsletter](/es/api/newsletter/overview)        |
| Perfil             |   4   | [Perfil](/es/api/profile/overview)               |
| Eventos / Webhooks |   4   | [Eventos](/es/api/events/overview)               |
| Chatwoot           |   3   | [Chatwoot](/es/api/chatwoot/overview)            |

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Autenticación" icon="key" href="/es/guide/authentication">
    Entiende TokenAccount vs TokenInstance, los mismos tokens que usa el MCP.
  </Card>

  <Card title="Conceptos" icon="lightbulb" href="/es/guide/concepts">
    Instancias, JIDs y los conceptos que manipulan las tools.
  </Card>

  <Card title="Referencia de la API" icon="book" href="/es/api/introduction">
    El detalle de cada endpoint, equivalente a cada tool del MCP.
  </Card>

  <Card title="Eventos" icon="bolt" href="/es/api/events/overview">
    Recibe mensajes en tiempo real vía webhook o WebSocket.
  </Card>
</CardGroup>