Connecting via MCP

The RyzeAPI MCP server exposes the platform as tools an AI client can call directly, via the Model Context Protocol. 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.

85 tools

Cover all 11 API modules, from sending messages to administering instances.

Streamable HTTP

The MCP’s standard HTTP transport, no local install: just point your client at the URL.

Multi-tenant

One server serves many clients; each session is isolated and uses its own token.

No stored credentials

The server keeps no tokens. You send yours on every session, through the headers.

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.

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 for the difference between the two tokens.

Configure your client

Claude Code (CLI)
Config file (JSON)
Test with curl

Add the server with HTTP transport and pass your token in the header:

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

To pin a default instance, add another header:

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

For Claude Desktop and other clients that use an MCP server config file:

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

The instance field is optional.

To confirm the endpoint is up and your token is accepted, initialise an MCP session:

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" }
    }
  }'

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.

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:

🟢 Read-only

Queries that change nothing (whoami, instance_list, contact_list).

🟡 Write

Create or change data (send_text, group_create, webhook_set).

🔴 Destructive

Remove resources (instance_delete, chat_delete, message_delete).

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
Instances	13	Instance
Messages	14	Messages
Calls	2	Calls
Chat	25	Chat
Groups	9	Groups
Communities	4	Communities
Newsletter	5	Newsletter
Profile	4	Profile
Events / Webhooks	4	Events
Chatwoot	3	Chatwoot

Next steps

Authentication

Understand TokenAccount vs TokenInstance, the same tokens the MCP uses.

Concepts

Instances, JIDs, and the concepts the tools operate on.

API Reference

The detail of each endpoint, equivalent to each MCP tool.

Events

Receive messages in real time via webhook or WebSocket.

85 tools

Streamable HTTP

Multi-tenant

No stored credentials

​Endpoint and transport

​Authentication

​Configure your client

​First call: whoami

​The 85 tools

🟢 Read-only

🟡 Write

🔴 Destructive

​Next steps

Authentication

Concepts

API Reference

Events

Endpoint and transport

Authentication

Configure your client

First call: `whoami`

The 85 tools

Next steps