O que realmente quebra no seu servidor MCP em 2026-07-28

A especificação MCP de 2026-07-28 é a maior revisão desde o lançamento do protocolo e não é compatível com versões anteriores. O candidato a lançamento foi bloqueado em 21 de maio de 2026, e a especificação é ratificada em 28 de julho. Se você executar um servidor do Protocolo de Contexto de Modelo em produção, parte do seu código deixará de funcionar nesse dia.

A maioria dos artigos até agora explica o porquê (o MCP se tornou sem estado, aqui está o que isso significa para escalabilidade). Essa parte é genuinamente interessante. Mas se você mantém um servidor, a pergunta que você realmente tem é mais específica: quais linhas do meu código quebram e o que eu mudo nelas. Este post é essa lista. Sete mudanças, cada uma com o antes/depois e um grep que você pode executar agora mesmo.

Estou citando números SEP ao longo do texto para que você possa ler as propostas de origem por conta própria. Não leve minha palavra por nada disso.

1. A sessão foi removida (SEP-2567)

Esta é a mudança principal. O cabeçalho Mcp-Session-Id e a sessão em nível de protocolo que ele criava foram removidos. O transporte de 2026-07-28 é sem estado: qualquer solicitação pode chegar a qualquer instância do servidor.

A vantagem prática é real. Antes, um servidor remoto precisava de sessões persistentes, um armazenamento de sessão compartilhado e um gateway inteligente o suficiente para rotear por sessão. Agora, ele opera atrás de um balanceador de carga simples em round-robin.

O custo é que qualquer coisa que leia ou escreva uma sessão não tem mais uma sessão para ler ou escrever.

Procure um armazenamento de sessão SDK:

// antes — SDK TS
new StreamableHTTPServerTransport({
  sessionIdGenerator: () => randomUUID(),
});

// depois — sem id de sessão, sem armazenamento por sessão
new StreamableHTTPServerTransport({
  sessionIdGenerator: undefined,
});

O que costumava viver na sessão agora viaja em _meta em cada solicitação: versão do protocolo, informações do cliente, capacidades do cliente. Leia-os por solicitação em vez de procurá-los pelo id da sessão.

grep -rn "Mcp-Session-Id\|sessionIdGenerator\|sessionStore" src/

Se sua aplicação realmente precisa de estado entre chamadas, faça o que as APIs HTTP sempre fizeram: crie um identificador explícito a partir de uma ferramenta (um cart_id, um run_id) e faça o modelo passá-lo de volta como um argumento comum. Esse agora é seu mecanismo de estado, não o transporte.

2. O handshake de inicialização foi removido (SEP-2575)

Não há mais uma rodada de initialize / initialized. A negociação que costumava acontecer uma vez no momento da conexão foi eliminada, porque sem uma sessão não há "momento de conexão" para fixá-la.

Os mesmos dados (versão do protocolo, informações do cliente, capacidades) agora chegam em _meta em cada solicitação. Se você tem código que roda uma vez em initialize para armazenar capacidades e lê-las depois, esse padrão não se sustenta mais. Mova as verificações de capacidade para onde você as utiliza.

grep -rn "initialized\|onInitialize\|InitializeRequestSchema" src/

3. O código de erro -32002 se torna -32602 (SEP-2164)

Pequeno, mecânico e fácil de perder. A condição "recurso não encontrado" que usava o código personalizado do MCP -32002 agora retorna o padrão JSON-RPC -32602 (Parâmetros Inválidos). A especificação é clara sobre isso: se seu cliente corresponder ao literal -32002, atualize-o.

Isso afeta de duas maneiras. Se você lançar -32002 de um servidor, mude isso. Se você corresponder a ele no código do cliente ou nos testes, mude isso também.

// antes
throw new McpError(-32002, "Recurso desconhecido");
// depois
throw new McpError(-32602, "Recurso desconhecido");

grep -rn "32002" src/ test/

4. Dois novos cabeçalhos de roteamento obrigatórios (SEP-2243)

O transporte HTTP Streamable agora requer os cabeçalhos Mcp-Method e Mcp-Name. O objetivo é permitir que um balanceador de carga roteie sem ler o corpo da solicitação, que é o que faz a história do round-robin funcionar. Se você estiver atrás de um proxy ou gateway que filtra ou encaminha cabeçalhos, certifique-se de que esses dois passem. Se você implementar HTTP manualmente em vez de usar um transporte SDK, agora você os define.

5. ttlMs e cacheScope em respostas de list/read (SEP-2549)

list e read as respostas agora podem carregar ttlMs e cacheScope, para que os clientes possam armazenar em cache os resultados sem manter um fluxo persistente aberto. Isso é aditivo, não uma quebra. Mas se sua lista de ferramentas ou conjunto de recursos for efetivamente estática, definir um ttlMs é um desempenho gratuito para cada cliente que o chama. Vale a pena uma passada uma vez que o resto compila.

6. Roots, sampling e logging estão obsoletos (SEP-2577)

Esses três primitivos ainda funcionam em 2026-07-28, mas estão em uma pista documentada de 12 meses para remoção (cerca de julho de 2027). Nada quebra no primeiro dia. Trate isso como avisos, não incêndios:

• sampling (o servidor pede ao cliente para executar uma chamada LLM): substitua por uma chamada de API LLM direta do seu próprio código.
• roots (o cliente anuncia raízes do sistema de arquivos): passe o contexto de trabalho explicitamente como entradas da ferramenta.
• logging (os métodos de protocolo logging/*): mude para stderr ou OpenTelemetry.

grep -rn "createMessage"\|ListRootsRequest\|sendLoggingMessage\|setLoggingLevel" src/

7. Tarefas movem-se do núcleo para uma extensão (SEP-2663)

Tarefas enviadas experimentalmente no protocolo central em 2025-11-25. O uso em produção empurrou isso para fora do núcleo e para uma extensão versionada (SEP-2663), construída na nova estrutura de extensões (SEP-2133). O r