Introdução

O servidor MCP do Inbox Autônomo é um servidor Model Context Protocol remoto que expõe as mesmas operações da API REST pública — inboxes, e-mails, agentes, execuções, webhooks e o log de eventos — como tools que um cliente de IA pode chamar. Você o conecta por URL; não há nada para instalar.

Ele é servido em host próprio, mcp.inbox.kobana.com.br, com transporte Streamable HTTP em modo stateless e autenticação por Bearer token, emitido para o servidor MCP pelo authorization server da Kobana. Não há certificado de cliente: diferente de /v1, o host MCP não tem camada mTLS, e o OAuth 2.1 ocupa o lugar dela.

:::info Disponibilidade O servidor, suas 53 tools, os resources e os prompts estão implementados, e a autenticação passa pelo authorization server da Kobana: pelo fluxo OAuth 2.1, em que o cliente recebe só a URL e faz o login sozinho, ou por um token pessoal criado na sua conta Kobana. A borda dedicada (distribution mcp.inbox.*, WAF e DNS) ainda está sendo provisionada. :::

Quando usar

	API REST (/v1)	Servidor MCP (este)	Servidores stdio
Consumidor	seu backend	um cliente de IA (Claude, ChatGPT, uma IDE)	um cliente de IA na sua máquina
Configuração	certificado + token, fora de banda	uma URL	build local + mcp.json
Transporte	HTTPS/REST	Streamable HTTP (JSON-RPC 2.0)	stdio
Autenticação	mTLS + Bearer JWT emitido para a API	OAuth 2.1 ou token pessoal, sempre emitido para o servidor MCP	mTLS + Bearer JWT
Superfície	os endpoints de /v1	53 tools sobre os mesmos endpoints, mais resources e prompts sobre elas	um servidor por recurso

O servidor MCP não substitui a API REST — cada tool despacha para o endpoint dono da operação, então filtros, regras de upsert, validação e isolamento multi-tenant são exatamente os mesmos. Se você está escrevendo código, use a API REST. Se está conectando um assistente, use este.

Primeiros passos

1. Aponte seu cliente para a URL do servidor — veja Endpoints e Clientes.

2. Autorize. O cliente abre o login da Kobana; entre com uma conta da organização e autorize o acesso. Veja Autenticação.

3. Liste as tools para confirmar o que o seu acesso alcança — pergunte ao assistente ou, com um token emitido para o servidor MCP em mãos:

   curl https://mcp.inbox.kobana.com.br/ \
     -H "Authorization: Bearer $MCP_TOKEN" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "MCP-Protocol-Version: 2025-06-18" \
     -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }'

4. Explore as tools — a categoria Recursos no menu lateral documenta cada tool com seus parâmetros.

O que quem chama enxerga

tools/list é filtrado pelo que quem chama consegue de fato executar, em dois eixos:

• os escopos (ou o nível de acesso) do token apresentado — o teto do cliente conectado;
• as permissões da pessoa que o token nomeia — o que essa pessoa pode fazer na organização dela.

Um token que carrega apenas inbox/emails enxerga só as tools de leitura de e-mail. Uma pessoa sem emails.reprocess nunca vê emails_reprocess, mesmo portando um token que permitiria. Um agente não é informado sobre capacidades que não pode usar.

Próximos passos

• Autenticação — o fluxo OAuth, o token pessoal, escopos e permissões, e os modos de falha.
• Endpoints — hosts por ambiente e rotas servidas.
• Transporte — Streamable HTTP, métodos JSON-RPC e headers.
• Resources e prompts — documentos por URI, prompts prontos, autocompletar e a confirmação de tools destrutivas.
• Clientes — conectando Claude, Claude Code e outros clientes MCP.
• Limite de requisições — throttling e headers de resposta.
• Paginação — paginação por cursor nos resultados das tools.
• Idempotência — idempotency_key para retries seguros.
• Erros — erros de protocolo e erros de tool.