Conexão via MCP

O servidor MCP da RyzeAPI expõe a plataforma como ferramentas que um cliente de IA pode chamar diretamente, via Model Context Protocol. Em vez de você escrever as chamadas HTTP, o modelo (Claude, por exemplo) usa 85 tools para enviar mensagens, gerenciar instâncias, grupos, chats, webhooks, Chatwoot e mais.

85 tools

Cobrem 11 módulos da API, do envio de mensagens à administração de instâncias.

Streamable HTTP

Transporte HTTP padrão do MCP, sem instalação local: basta apontar seu cliente para a URL.

Multi-tenant

Um servidor atende vários clientes; cada sessão é isolada e usa o seu próprio token.

Sem credenciais armazenadas

O servidor não guarda nenhum token. Você envia o seu a cada sessão, pelos headers.

Endpoint e transporte


Endpoint	`https://ryzeapi.cloud/mcp`
Transporte	Streamable HTTP (`POST` / `GET` / `DELETE` em `/mcp`)
Liveness	`GET /healthz` (sem autenticação)

Autenticação

A autenticação é por sessão: cada cliente envia o seu próprio token da RyzeAPI nos headers ao iniciar a sessão. São os mesmos tokens da API REST.

Header	Obrigatório	Descrição
`token`	✅	Seu token da RyzeAPI (TokenAccount ou TokenInstance). `Authorization: Bearer <token>` também funciona.
`instance`	,	Instância padrão da sessão. Cada tool pode sobrescrever pelo argumento `instance`.

Use TokenAccount se quiser operar várias instâncias na mesma sessão (cada tool informa a instance). Use TokenInstance + header instance se for trabalhar com uma única instância. Veja Autenticação para a diferença entre os dois tokens.

Configure seu cliente

Claude Code (CLI)
Arquivo de configuração (JSON)
Testar com curl

Adicione o servidor com transporte HTTP e passe seu token no header:

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

Para fixar uma instância padrão, adicione outro header:

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

Para Claude Desktop e outros clientes que usam um arquivo de configuração de servidores MCP:

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

O campo instance é opcional.

Para confirmar que o endpoint está no ar e seu token é aceito, inicialize uma sessão MCP:

curl -X POST "https://ryzeapi.cloud/mcp" \
  -H "token: SEU_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" }
    }
  }'

Trate o token como credencial. Prefira variáveis de ambiente ou o cofre de segredos do seu cliente, nunca deixe o token fixo em repositórios ou no frontend.

Primeira chamada: `whoami`

Depois de conectar, peça ao seu cliente para chamar a tool whoami. Ela confirma que o token está válido e mostra a instância padrão da sessão, é a forma mais rápida de validar a conexão antes de qualquer operação.

As 85 tools

As ferramentas seguem a convenção recurso_ação (ex.: tag_create, message_forward), com a família send_* para tudo que envia uma nova mensagem ou chamada. Cada tool carrega anotações que permitem ao cliente pedir confirmação em ações sensíveis:

🟢 Somente leitura

Consultas que não alteram nada (whoami, instance_list, contact_list).

🟡 Escrita

Criam ou alteram dados (send_text, group_create, webhook_set).

🔴 Destrutivo

Removem recursos (instance_delete, chat_delete, message_delete).

Os 11 módulos correspondem 1:1 às seções da Referência da API. Os argumentos de cada tool usam os mesmos nomes de campo da API REST, então a documentação de cada endpoint vale também para a tool equivalente:

Módulo	Tools	Referência
Saúde	2	Observabilidade
Instâncias	13	Instância
Mensagens	14	Mensagens
Chamadas	2	Chamadas
Chat	25	Chat
Grupos	9	Grupos
Comunidades	4	Comunidades
Newsletter	5	Newsletter
Perfil	4	Perfil
Eventos / Webhooks	4	Eventos
Chatwoot	3	Chatwoot

Próximos passos

Autenticação

Entenda TokenAccount vs TokenInstance, os mesmos tokens usados pelo MCP.

Conceitos

Instâncias, JIDs e os conceitos que as tools manipulam.

Referência da API

Detalhe de cada endpoint, equivalente a cada tool do MCP.

Eventos

Receba mensagens em tempo real por webhook ou WebSocket.

85 tools

Streamable HTTP

Multi-tenant

Sem credenciais armazenadas

​Endpoint e transporte

​Autenticação

​Configure seu cliente

​Primeira chamada: whoami

​As 85 tools

🟢 Somente leitura

🟡 Escrita

🔴 Destrutivo

​Próximos passos

Autenticação

Conceitos

Referência da API

Eventos

Endpoint e transporte

Autenticação

Configure seu cliente

Primeira chamada: `whoami`

As 85 tools

Próximos passos