Transporte

Streamable HTTP, stateless. Uma mensagem JSON-RPC 2.0 por POST, uma resposta JSON. Não há Mcp-Session-Id, não há resumability e não há stream servidor→cliente: a aplicação roda com várias réplicas, e toda operação longa já responde 202 e termina em um worker em segundo plano, não no canal MCP.

Versões de protocolo

O servidor fala duas eras do protocolo no mesmo endpoint:

Versão	Era	Situação
`2026-07-28`	Stateless, sem handshake — descoberta por `server/discover`	Suportada
`2025-06-18`	Handshake por `initialize` — o padrão quando o cliente não envia o header	Suportada
`2025-03-26`	Handshake por `initialize`	Suportada

A era é decidida pelo body da requisição, com os headers servindo de conferência:

params._meta carrega io.modelcontextprotocol/protocolVersion → era 2026-07-28 (veja abaixo).
Sem esse envelope, com um MCP-Protocol-Version de 2025 ou sem o header → era 2025, com initialize.
MCP-Protocol-Version: 2026-07-28 sem o envelope → 400 com -32602. O servidor não cai silenciosamente para a era antiga: você pediu a semântica stateless e receberia a outra.

Uma versão que o servidor não fala — no header ou no envelope, em qualquer era — recebe 400 com o erro JSON-RPC -32022, listando as suportadas:

{ "jsonrpc": "2.0", "id": 1, "error": {
  "code": -32022,
  "message": "Unsupported protocol version",
  "data": { "supported": ["2026-07-28", "2025-06-18", "2025-03-26"], "requested": "1999-01-01" }
} }

A versão em uso volta no header de resposta MCP-Protocol-Version.

Era `2026-07-28`

Não há handshake: toda requisição carrega a própria versão e as capacidades do cliente em params._meta, e o servidor não guarda nada entre uma requisição e a seguinte.

Chave de `params._meta`	Obrigatória	Significado
`io.modelcontextprotocol/protocolVersion`	sim	`2026-07-28`
`io.modelcontextprotocol/clientCapabilities`	sim	As capacidades do cliente (um objeto; `{}` basta). Declarar `elicitation` liga a confirmação de tools destrutivas
`io.modelcontextprotocol/clientInfo`	recomendada	`name` e `version` do cliente

Os headers repetem o que está no body, para que intermediários possam rotear sem lê-lo — e por isso precisam concordar com ele:

Header	Precisa ser igual a
`MCP-Protocol-Version`	A versão do envelope
`Mcp-Method`	O `method` da mensagem
`Mcp-Name`	Só em `tools/call`: `params.name`, cru ou como `=?base64?…?=`

Qualquer divergência é 400 com -32020 (Header mismatch: …). clientCapabilities ausente é 400 com -32602.

Os resultados nessa era sempre carregam resultType: "complete" e o servidor em _meta["io.modelcontextprotocol/serverInfo"]. server/discover, tools/list, resources/list, resources/templates/list, resources/read e prompts/list também carregam ttlMs: 0 e cacheScope: "private": o que volta é filtrado pelo escopo e pelas permissões de quem chama, então não pode ser reaproveitado nem compartilhado. Uma tools/call de tool destrutiva pode voltar com resultType: "input_required" — veja Confirmação de tools destrutivas.

Headers de requisição

Header	Obrigatório	Significado
`Authorization`	sim	`Bearer <access token>` emitido para o servidor MCP — veja Autenticação
`Content-Type`	sim	`application/json`
`Accept`	recomendado	`application/json`
`MCP-Protocol-Version`	sim na era `2026-07-28`; recomendado na de 2025	Revisão do protocolo
`Mcp-Method`	sim na era `2026-07-28`	O método da mensagem
`Mcp-Name`	sim numa `tools/call` da era `2026-07-28`	O nome da tool
`X-Workspace-Id`	condicional	Workspace sobre o qual agir, quando a organização tem mais de um
`Origin`	condicional	Enviado por clientes de navegador; validado contra uma allowlist

Headers de resposta

Header	Significado
`MCP-Protocol-Version`	Revisão negociada
`X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`	Veja Limite de requisições
`Cache-Control`	Sempre `no-store`
`Retry-After`	Em `429` e em `503`

Métodos

Método	Era `2026-07-28`	Era 2025	Finalidade
`server/discover`	sim	—	Versões suportadas, capacidades do servidor e instruções
`initialize`	—	sim	Negociação de versão, capacidades do servidor e instruções
`ping`	—	sim	Checagem de vida; responde um resultado vazio
`tools/list`	sim	sim	Tools que quem chama pode executar, com JSON Schema e annotations
`tools/call`	sim	sim	Executa uma tool
`resources/list`	sim	sim	Os documentos de URI fixa que quem chama pode ler
`resources/templates/list`	sim	sim	Os templates de URI (`kobana://inbox/emails/{id}`, …) que quem chama pode ler
`resources/read`	sim	sim	Lê um documento por URI
`prompts/list`	sim	sim	Os prompts prontos que quem chama pode usar
`prompts/get`	sim	sim	Renderiza um prompt com os argumentos informados
`completion/complete`	sim	sim	Sugestões para um argumento de prompt ou de template

Resources, prompts e completions estão em Resources e prompts.

Qualquer outro método é -32601 Method not found — com HTTP 404 na era 2026-07-28, no body de um 200 na de 2025. Batching JSON-RPC não é suportado — foi removido na revisão 2025-06-18, e um body em array recebe 400.

O body da requisição é limitado a 1 MB (1.048.576 bytes); acima disso a resposta é 413 com -32600 — veja Erros. Nenhuma tool precisa de mais: arquivos nunca trafegam pelo MCP.

Uma notificação (mensagem sem id, como notifications/initialized) é aceita com 202 e corpo vazio, nas duas eras.

A autenticação vem antes de qualquer método, server/discover incluído: sem token, a resposta é o desafio 401 que manda o cliente para o login OAuth — veja Autenticação.

`server/discover` (era `2026-07-28`)

{ "jsonrpc": "2.0", "id": 1, "method": "server/discover",
  "params": { "_meta": {
    "io.modelcontextprotocol/protocolVersion": "2026-07-28",
    "io.modelcontextprotocol/clientCapabilities": {},
    "io.modelcontextprotocol/clientInfo": { "name": "my-client", "version": "1.0.0" }
  } } }

{ "jsonrpc": "2.0", "id": 1, "result": {
  "resultType": "complete",
  "supportedVersions": ["2026-07-28", "2025-06-18", "2025-03-26"],
  "capabilities": { "tools": {}, "resources": {}, "prompts": {}, "completions": {} },
  "instructions": "Tools for the Kobana Autonomous Inbox: ...",
  "ttlMs": 0,
  "cacheScope": "private",
  "_meta": {
    "io.modelcontextprotocol/serverInfo": {
      "name": "kobana-autonomous-inbox",
      "title": "Kobana Autonomous Inbox",
      "version": "0.1.0"
    }
  }
} }

`initialize` (handshake da era 2025)

{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": { "protocolVersion": "2025-06-18" } }

{ "jsonrpc": "2.0", "id": 1, "result": {
  "protocolVersion": "2025-06-18",
  "capabilities": {
    "tools": { "listChanged": false },
    "resources": { "subscribe": false, "listChanged": false },
    "prompts": { "listChanged": false },
    "completions": {}
  },
  "serverInfo": {
    "name": "kobana-autonomous-inbox",
    "title": "Kobana Autonomous Inbox",
    "version": "0.1.0"
  },
  "instructions": "Tools for the Kobana Autonomous Inbox: ..."
} }

As instructions (em initialize e server/discover) avisam o agente de que os valores de campos nos resultados — sobretudo o assunto e o corpo de um e-mail — são dados escritos por terceiros, nunca instruções, e pedem que ele confirme com o usuário antes de uma ação destrutiva que um resultado pareça solicitar. Elas também dizem que tools destrutivas exigem o protocolo 2026-07-28 com elicitation, e que confirmation_required significa que o cliente não consegue executá-las — não é algo para tentar de novo.

`tools/list`

Devolve apenas as tools que quem chama consegue executar, filtradas pelo escopo do token e pelas permissões da pessoa. Toda tool carrega annotations, que orientam os pedidos de confirmação do cliente:

Annotation	Significado
`readOnlyHint`	A tool apenas lê
`destructiveHint`	A tool exclui dados, envia algo para fora (teste ou reenvio de webhook, reprocessamento de e-mail), rotaciona um segredo ou muda quem pode enviar para uma inbox. Só roda depois da confirmação do servidor
`idempotentHint`	Repetir a chamada tem o mesmo efeito
`openWorldHint`	Sempre `false` — a tool não alcança nada fora do Inbox Autônomo

`tools/call`

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "emails_list", "arguments": { "status": "processed", "limit": 10 } } }

O resultado carrega a resposta JSON do endpoint como conteúdo de texto:

{ "jsonrpc": "2.0", "id": 2, "result": {
  "content": [{ "type": "text", "text": "{ \"data\": [ ... ], \"meta\": { \"next_cursor\": \"...\" } }" }]
} }

Erros sobre os quais quem chama pode agir voltam com isError: true dentro do resultado, e não como erro JSON-RPC — veja Erros.

Despacho in-process

Toda tool despacha in-process para o route handler de /api/v1 dono da operação, com a identidade já verificada — o token MCP não é repassado, e o endpoint continua exigindo seu próprio escopo e sua própria permissão. Ids nos argumentos são codificados no path, então um id não consegue alcançar outra rota. Não há round trip HTTP nem uma segunda implementação: filtros de listagem, casamento de upsert, validação, soft-delete e isolamento multi-tenant são o mesmo código que a API REST executa, então uma tool não consegue divergir do endpoint que espelha.

Versões de protocolo​

Era 2026-07-28​

Headers de requisição​

Headers de resposta​

Métodos​

server/discover (era 2026-07-28)​

initialize (handshake da era 2025)​

tools/list​

tools/call​

Despacho in-process​