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

# Connecting via MCP

> Connect AI clients (Claude and others) to RyzeAPI through the MCP server, with 85 ready-to-use tools

The **RyzeAPI MCP server** exposes the platform as tools an AI client can call directly, via the [Model Context Protocol](https://modelcontextprotocol.io). Instead of writing the HTTP calls yourself, the model (Claude, for example) uses **85 tools** to send messages, manage instances, groups, chats, webhooks, Chatwoot, and more.

<CardGroup cols={2}>
  <Card title="85 tools" icon="screwdriver-wrench">
    Cover all 11 API modules, from sending messages to administering instances.
  </Card>

  <Card title="Streamable HTTP" icon="plug">
    The MCP's standard HTTP transport, no local install: just point your client at the URL.
  </Card>

  <Card title="Multi-tenant" icon="users">
    One server serves many clients; each session is isolated and uses its own token.
  </Card>

  <Card title="No stored credentials" icon="shield-check">
    The server keeps no tokens. You send yours on every session, through the headers.
  </Card>
</CardGroup>

## Endpoint and transport

|               |                                                       |
| ------------- | ----------------------------------------------------- |
| **Endpoint**  | `https://ryzeapi.cloud/mcp`                           |
| **Transport** | Streamable HTTP (`POST` / `GET` / `DELETE` on `/mcp`) |
| **Liveness**  | `GET /healthz` (no authentication)                    |

## Authentication

Authentication is **per session**: each client sends its own RyzeAPI token in the headers when the session starts. These are the same tokens as the REST API.

| Header     | Required | Description                                                                                             |
| ---------- | :------: | ------------------------------------------------------------------------------------------------------- |
| `token`    |     ✅    | Your RyzeAPI token (**TokenAccount** or **TokenInstance**). `Authorization: Bearer <token>` also works. |
| `instance` |     ,    | Default instance for the session. Each tool can override it via the `instance` argument.                |

<Tip>
  Use a **TokenAccount** if you want to operate several instances in the same session (each tool passes the `instance`). Use a **TokenInstance** + the `instance` header if you'll work with a single instance. See [Authentication](/en/guide/authentication) for the difference between the two tokens.
</Tip>

## Configure your client

<Tabs>
  <Tab title="Claude Code (CLI)">
    Add the server with HTTP transport and pass your token in the header:

    ```bash theme={null}
    claude mcp add --transport http ryzeapi https://ryzeapi.cloud/mcp \
      --header "token: YOUR_RYZEAPI_TOKEN"
    ```

    To pin a default instance, add another header:

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

  <Tab title="Config file (JSON)">
    For Claude Desktop and other clients that use an MCP server config file:

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

    The `instance` field is optional.
  </Tab>

  <Tab title="Test with curl">
    To confirm the endpoint is up and your token is accepted, initialise an MCP session:

    ```bash theme={null}
    curl -X POST "https://ryzeapi.cloud/mcp" \
      -H "token: YOUR_RYZEAPI_TOKEN" \
      -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>
  Treat the `token` as a credential. Prefer environment variables or your client's secret store, never hardcode the token in repositories or in the frontend.
</Warning>

## First call: `whoami`

After connecting, ask your client to call the **`whoami`** tool. It confirms the token is valid and shows the session's default instance, the fastest way to validate the connection before any operation.

## The 85 tools

Tools follow the **`resource_action`** convention (e.g. `tag_create`, `message_forward`), with the **`send_*`** family for anything that sends a new message or call. Each tool carries annotations that let the client ask for confirmation on sensitive actions:

<CardGroup cols={3}>
  <Card title="🟢 Read-only" icon="eye">
    Queries that change nothing (`whoami`, `instance_list`, `contact_list`).
  </Card>

  <Card title="🟡 Write" icon="pen">
    Create or change data (`send_text`, `group_create`, `webhook_set`).
  </Card>

  <Card title="🔴 Destructive" icon="trash">
    Remove resources (`instance_delete`, `chat_delete`, `message_delete`).
  </Card>
</CardGroup>

The 11 modules map 1:1 to the API Reference sections. Each tool's arguments use the same field names as the REST API, so the docs for each endpoint apply to the equivalent tool too:

| Module            | Tools | Reference                                       |
| ----------------- | :---: | ----------------------------------------------- |
| Health            |   2   | [Observability](/en/api/observability/overview) |
| Instances         |   13  | [Instance](/en/api/instance/overview)           |
| Messages          |   14  | [Messages](/en/api/messages/overview)           |
| Calls             |   2   | [Calls](/en/api/calls/fake)                     |
| Chat              |   25  | [Chat](/en/api/chat/overview)                   |
| Groups            |   9   | [Groups](/en/api/groups/overview)               |
| Communities       |   4   | [Communities](/en/api/communities/overview)     |
| Newsletter        |   5   | [Newsletter](/en/api/newsletter/overview)       |
| Profile           |   4   | [Profile](/en/api/profile/overview)             |
| Events / Webhooks |   4   | [Events](/en/api/events/overview)               |
| Chatwoot          |   3   | [Chatwoot](/en/api/chatwoot/overview)           |

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/en/guide/authentication">
    Understand TokenAccount vs TokenInstance, the same tokens the MCP uses.
  </Card>

  <Card title="Concepts" icon="lightbulb" href="/en/guide/concepts">
    Instances, JIDs, and the concepts the tools operate on.
  </Card>

  <Card title="API Reference" icon="book" href="/en/api/introduction">
    The detail of each endpoint, equivalent to each MCP tool.
  </Card>

  <Card title="Events" icon="bolt" href="/en/api/events/overview">
    Receive messages in real time via webhook or WebSocket.
  </Card>
</CardGroup>