MCP 2025-06-18: o que quebra em agentes e integrações ao migrar de versão

A especificação oficial do Model Context Protocol↳MCP7 conteúdosArquitetura de Sistemas Cognitivos: Integração de RAG, MCP e LLMs no Ecossistema .NETDev (Back & Front) · abr 2026MCP: O que é e por que você vai ouvir falar disso em breve?AI · jul 2025Agentes de IA com LLMs de Código Aberto: Integração Prática com o Model Context Protocol (MCP)AI · ago 2025Ver tudo em AI → documenta, no changelog da revisão 2025-06-18, um conjunto de mudanças que remodelam partes centrais do protocolo usado para conectar agentes de IA a ferramentas e dados externos. A revisão foi publicada em 18 de junho de 2025, ou seja, já tem mais de um ano. Mesmo assim, é comum encontrar servidores e clientes MCP em produção que ainda falam a revisão anterior, 2025-03-26, e que vão quebrar (ou já quebraram, sem que alguém tenha percebido) ao conversar com a contraparte atualizada.

Esse é o problema prático: MCP não tem um mecanismo de aviso explícito quando as duas pontas divergem de versão em pontos de comportamento, só na negociação do protocolo. Isso significa que erros de integração aparecem como falha silenciosa, timeout ou resposta mal interpretada, não como uma mensagem clara de "versão incompatível". Vale mapear exatamente onde isso acontece antes de atualizar um SDK em produção.

O que mudou, resumido

A fonte lista as mudanças principais da revisão. As quatro que mais afetam código já escrito são:

Além dessas, a revisão também reclassifica servidores MCP como OAuth Resource Servers, exige que clientes implementem Resource Indicators (RFC 8707) e adiciona suporte a links de recursos no resultado de chamadas de tool. São mudanças relevantes para quem expõe servidores MCP remotos com autenticação, mas o impacto imediato em código de agente está nas quatro da tabela acima.

Batching desaparece: quem envia array quebra

A revisão 2025-03-26 herdava do JSON-RPC 2.0 a possibilidade de empacotar várias requisições num único array, útil para reduzir round-trips em agentes que chamam várias tools seguidas. A 2025-06-18 remove esse suporte por completo. Um payload como este, válido na revisão anterior, deixa de ser aceito:

[
  { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "searchDocs", "arguments": { "query": "pricing" } } },
  { "jsonrpc": "2.0", "id": 2, "method": "resources/read", "params": { "uri": "file:///docs/pricing.md" } }
]

Um servidor já migrado para 2025-06-18 não espera receber um array na raiz da mensagem; o parse falha ou o servidor responde com erro de requisição inválida. Quem construiu um orquestrador de agente que agrupa chamadas para economizar latência precisa reescrever esse trecho para disparar cada chamada como mensagem independente, seja em sequência, seja em paralelo sobre múltiplas conexões. Não existe mais atalho de protocolo para isso: a economia de round-trip tem que vir de outro lugar, como paralelismo na camada de transporte.

Saída estruturada muda o contrato de CallToolResult

Antes da revisão, uma tool só podia devolver blocos de content (texto, imagem, referência a recurso). Agentes que precisavam de dados estruturados costumavam serializar JSON dentro de um bloco de texto e fazer o parse manual no lado do cliente. A revisão 2025-06-18 formaliza isso: uma tool pode declarar outputSchema e devolver structuredContent junto (ou no lugar) do content tradicional.

{
  "content": [{ "type": "text", "text": "{\"temperature\": 22, \"unit\": \"C\"}" }],
  "structuredContent": { "temperature": 22, "unit": "C" }
}

O ponto de quebra aqui é sutil: se o código do cliente sempre fez JSON.parse(result.content[0].text) para extrair dados de uma tool, ele continua funcionando enquanto o servidor mantiver os dois campos por compatibilidade. Mas nada obriga o autor da tool a manter essa redundância depois de migrar para outputSchema; muitos param de popular content com texto equivalente, porque o structuredContent já cobre o caso. Nesse cenário, o parser antigo recebe um array content vazio ou com outro formato e quebra sem aviso. Vale checar se o cliente já lê structuredContent diretamente antes de depender dele.

Elicitation: um tipo de mensagem que cliente antigo não sabe tratar

A elicitation é o recurso mais novo da lista e também o que introduz um tipo de interação que simplesmente não existia antes: durante uma chamada de tool, o servidor pode enviar elicitation/create pedindo ao cliente que colete mais informação do usuário, como confirmar um valor ou escolher uma opção. Isso exige negociação explícita de capability no initialize; um cliente só deve receber esse tipo de pedido se declarou suportar elicitation.

Em resumo: o risco de quebra aqui é duplo. Se o cliente não implementa um handler para elicitation/create, a chamada de tool fica pendurada esperando uma resposta que nunca vem, ou o cliente retorna erro genérico de método desconhecido. E se o servidor dispara elicitation para um cliente que não negociou a capability, a própria especificação trata isso como violação do ciclo de vida, algo que a mudança de SHOULD para MUST no changelog torna mais estrito de se tolerar.

Cabeçalho MCP-Protocol-Version vira obrigatório em HTTP

Para quem usa o transporte HTTP (streamable HTTP, não stdio), a revisão passa a exigir que toda requisição enviada depois do initialize inclua o cabeçalho MCP-Protocol-Version com o valor negociado. Antes isso era recomendação; agora é requisito. Gateways, proxies e balanceadores que ficam entre cliente e servidor MCP e não repassam esse cabeçalho corretamente passam a gerar respostas rejeitadas, mesmo que o payload JSON-RPC em si esteja correto.

O caminho que eu seguiria para migrar sem quebrar nada

Antes de trocar o SDK em produção, o roteiro que faz sentido seguir é:

1. Atualizar o SDK oficial (TypeScript↳TypeScript23 conteúdosTypeScript: ReadonlyArrayDev (Back & Front) · jun 2019Onde usar ANY no TypeScriptDev (Back & Front) · out 2025Tudo sobre o Node rodar TypeScript nativamente!Dev (Back & Front) · jul 2025Ver tudo em Dev (Back & Front) → ou Python) e ler o changelog completo linkado no GitHub do projeto, não só o resumo.
2. Buscar no código por qualquer ponto que monte um array de requisições JSON-RPC e separar em chamadas individuais.
3. Nos handlers de tools, conferir se o parser depende só de content[0].text e adicionar leitura de structuredContent quando a tool declarar outputSchema.
4. Verificar se o cliente declara a capability elicitation no initialize e implementar um handler mínimo para elicitation/create, mesmo que seja só repassar a pergunta à interface do agente.
5. No transporte HTTP, confirmar que MCP-Protocol-Version é enviado em toda requisição pós-initialize, inclusive em proxies no meio do caminho.
6. Rodar a suíte de integração contra um servidor que já fala 2025-06-18 antes de promover a mudança para produção.

Quando dá para esperar

Se a integração roda só sobre stdio, local, sem OAuth e sem depender de batching, o impacto imediato é menor: a maior parte das mudanças de autenticação e do cabeçalho HTTP simplesmente não se aplica. Ainda assim, vale checar qual revisão o servidor anuncia durante o initialize; se ele já negocia 2025-06-18, as mudanças de structuredContent e elicitation já estão em jogo, mesmo sem HTTP envolvido. Adiar a migração é razoável só enquanto as duas pontas combinarem a mesma revisão antiga, o que o ecossistema MCP tende a deixar de suportar com o tempo.

Fonte: Model Context Protocol — Especificação oficial, revisão 2025-06-18