Migração de um servidor MCP HTTP para 2026-07-28 com suporte a clientes antigos

Objetivo

Situação em 25 de outubro de 2026. Migrar um servidor MCP HTTP para a revisão 2026-07-28, preservando uma via de atendimento a clientes 2025-11-25 com suporte explícito. Antes da implantação, conferir novamente o transporte e os esquemas de mensagens da versão, além do suporte documentado pelo SDK escolhido. Este é um procedimento de aceitação proposto, não o relato de uma migração testada.

Pré-requisitos

Inventariar as revisões de protocolo dos clientes, os handlers de inicialização, o armazenamento de sessões, os callbacks, as assinaturas e as políticas de autorização. Preparar um endpoint de homologação atrás de um gateway semelhante ao de produção, uma configuração de reversão e clientes para ambas as revisões. Usar ferramentas de teste inofensivas e identidades de teste separadas. Registrar a versão efetiva do pacote do SDK; uma revisão de protocolo não é uma versão de pacote.

Passos

1. Separar os fluxos de protocolo. As regras de compatibilidade permitem os dois comportamentos em um único endpoint. Um initialize legado seleciona a semântica legada; os metadados modernos enviados em cada requisição selecionam o processamento sem estado. Preservar o comportamento negociado da revisão anterior enquanto seus clientes continuarem recebendo suporte. Não aplicar indiscriminadamente os requisitos modernos de cabeçalhos à inicialização legada.

2. Tornar as requisições autossuficientes. Exigir io.modelcontextprotocol/protocolVersion e io.modelcontextprotocol/clientCapabilities em params._meta. Incluir a identidade do cliente conforme recomendado, mas nunca usar essa identidade autodeclarada para autorizar o acesso. Deixar de deduzir capacidades ou contexto da aplicação a partir da conexão anterior. Expor identificadores explícitos para o estado que abrange várias chamadas.

3. Implementar descoberta e validação do transporte. Implementar server/discover, reproduzir a versão em MCP-Protocol-Version e validar os cabeçalhos obrigatórios em relação ao corpo. Um teste básico de descoberta para um endpoint de homologação sem autenticação é:

   curl --request POST 'https://mcp.example.com/mcp' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json, text/event-stream' \
     --header 'MCP-Protocol-Version: 2026-07-28' \
     --header 'Mcp-Method: server/discover' \
     --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"migration-check","version":"local"}}}}'
   

   Substituir a URL de exemplo. Para endpoints protegidos, usar o cliente de teste autenticado aprovado para a implantação; não desativar a autenticação para executar esta verificação.

4. Atualizar resultados e interações. Emitir resultType: "complete" para resultados comuns. Implementar MRTR para as operações interativas permitidas: retornar input_required e depois aceitar os inputResponses correspondentes e o requestState opaco, sem alterações, em uma requisição com novo ID. Verificar a integridade do estado quando ele afetar permissões ou lógica de negócio; vinculá-lo à identidade autenticada, ao prazo de validade e à operação de origem, conforme recomendado. Quando necessário, impor no servidor o consumo uma única vez.

5. Migrar notificações e cache. Substituir o fluxo independente de notificações via GET por subscriptions/listen. Preservar SSE restrito à requisição onde for usado, mas remover a retomada com Last-Event-ID: o fechamento de um fluxo de resposta sinaliza cancelamento. Adicionar ttlMs não negativo e o cacheScope adequado aos resultados completos abrangidos pela especificação de cache. Excluir do cache os resultados intermediários e os de novas tentativas de MRTR.

6. Testar deliberadamente a recuperação de incompatibilidades de versão. Uma versão moderna sem suporte retorna UnsupportedProtocolVersionError com as versões suportadas. Recomenda-se que os clientes tentem novamente com uma versão compatível. Em caso de HTTP 400, inspecionar o corpo JSON-RPC: erros modernos reconhecidos exigem correção ou seleção de versão; um corpo vazio ou não reconhecido permite recorrer à inicialização legada. Não regredir para uma versão anterior apenas porque uma requisição moderna válida foi rejeitada.

7. Testar a passagem pela infraestrutura da implantação. Na homologação, executar descoberta, obtenção de listas, uma chamada inofensiva, uma nova tentativa interativa e uma assinatura através do gateway. Repetir com um cliente legado e encaminhar requisições modernas a diferentes instâncias. Interromper uma resposta SSE inofensiva e verificar o cancelamento e a recuperação segura sem retomada do fluxo. Verificar a autorização de cada identidade e confirmar que os metadados das requisições chegam ao servidor sem alterações.

Resultado esperado

As duas revisões suportadas concluem seus respectivos fluxos de trabalho. As operações modernas não exigem sessão de transporte; os clientes legados preservam o ciclo de vida negociado. Manter a configuração antiga disponível até a aprovação nas verificações de aceitação.

Limites e base de verificação

A especificação citada define o comportamento do protocolo; os passos acima são um plano de verificação proposto para o operador. Eles não comprovam compatibilidade do SDK, segurança de novas tentativas em ações de negócio nem funcionamento bem-sucedido em um balanceador de carga específico. Esses aspectos exigem testes próprios da implantação.