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

# Conexão via MCP

> Conecte clientes de IA (Claude e outros) à RyzeAPI pelo servidor MCP, com 85 tools prontas para usar

O **servidor MCP da RyzeAPI** expõe a plataforma como ferramentas que um cliente de IA pode chamar diretamente, via [Model Context Protocol](https://modelcontextprotocol.io). 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.

<CardGroup cols={2}>
  <Card title="85 tools" icon="screwdriver-wrench">
    Cobrem 11 módulos da API, do envio de mensagens à administração de instâncias.
  </Card>

  <Card title="Streamable HTTP" icon="plug">
    Transporte HTTP padrão do MCP, sem instalação local: basta apontar seu cliente para a URL.
  </Card>

  <Card title="Multi-tenant" icon="users">
    Um servidor atende vários clientes; cada sessão é isolada e usa o seu próprio token.
  </Card>

  <Card title="Sem credenciais armazenadas" icon="shield-check">
    O servidor não guarda nenhum token. Você envia o seu a cada sessão, pelos headers.
  </Card>
</CardGroup>

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

<Tip>
  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](/pt/guide/authentication) para a diferença entre os dois tokens.
</Tip>

## Configure seu cliente

<Tabs>
  <Tab title="Claude Code (CLI)">
    Adicione o servidor com transporte HTTP e passe seu token no header:

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

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

  <Tab title="Arquivo de configuração (JSON)">
    Para Claude Desktop e outros clientes que usam um arquivo de configuração de servidores MCP:

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

    O campo `instance` é opcional.
  </Tab>

  <Tab title="Testar com curl">
    Para confirmar que o endpoint está no ar e seu token é aceito, inicialize uma sessão MCP:

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

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

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

<CardGroup cols={3}>
  <Card title="🟢 Somente leitura" icon="eye">
    Consultas que não alteram nada (`whoami`, `instance_list`, `contact_list`).
  </Card>

  <Card title="🟡 Escrita" icon="pen">
    Criam ou alteram dados (`send_text`, `group_create`, `webhook_set`).
  </Card>

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

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](/pt/api/observability/overview) |
| Instâncias         |   13  | [Instância](/pt/api/instance/overview)            |
| Mensagens          |   14  | [Mensagens](/pt/api/messages/overview)            |
| Chamadas           |   2   | [Chamadas](/pt/api/calls/fake)                    |
| Chat               |   25  | [Chat](/pt/api/chat/overview)                     |
| Grupos             |   9   | [Grupos](/pt/api/groups/overview)                 |
| Comunidades        |   4   | [Comunidades](/pt/api/communities/overview)       |
| Newsletter         |   5   | [Newsletter](/pt/api/newsletter/overview)         |
| Perfil             |   4   | [Perfil](/pt/api/profile/overview)                |
| Eventos / Webhooks |   4   | [Eventos](/pt/api/events/overview)                |
| Chatwoot           |   3   | [Chatwoot](/pt/api/chatwoot/overview)             |

## Próximos passos

<CardGroup cols={2}>
  <Card title="Autenticação" icon="key" href="/pt/guide/authentication">
    Entenda TokenAccount vs TokenInstance, os mesmos tokens usados pelo MCP.
  </Card>

  <Card title="Conceitos" icon="lightbulb" href="/pt/guide/concepts">
    Instâncias, JIDs e os conceitos que as tools manipulam.
  </Card>

  <Card title="Referência da API" icon="book" href="/pt/api/introduction">
    Detalhe de cada endpoint, equivalente a cada tool do MCP.
  </Card>

  <Card title="Eventos" icon="bolt" href="/pt/api/events/overview">
    Receba mensagens em tempo real por webhook ou WebSocket.
  </Card>
</CardGroup>