MCP 2026-07-28 Guia de Migração: Servidores sem estado

Resumo: MCP 2026-07-28 remove sessões no nível do protocolo e o handshake de inicialização obrigatório. As equipes de produção devem localizar dependências ocultas de sessão, adotar metadados por solicitação, implementar MRTR (Multi Round-Trip Requests), atualizar políticas do gateway e fazer canary do novo protocolo antes de aposentar o comportamento legado.

A especificação do Model Context Protocol lançada em 28 de julho de 2026 introduz a maior mudança arquitetural no MCP desde a adição do suporte a transporte remoto.

O protocolo agora usa um núcleo sem estado de solicitação e resposta. A troca obrigatória de initialize e notifications/initialized foi removida, Mcp-Session-Id foi retirado e cada solicitação carrega as informações de protocolo necessárias para processá-la.

A versão também introduz Multi Round-Trip Requests, cabeçalhos de roteamento HTTP, respostas de listas cacheáveis, comportamento de autorização mais rigoroso, uma estrutura de extensões e um ciclo de vida formal de desativação. Consulte o comunicado oficial do MCP 2026-07-28 e o changelog completo da especificação para detalhes no nível do protocolo.

Essas mudanças tornam servidores MCP remotos mais fáceis de escalar por trás de infraestrutura HTTP padrão. Elas não tornam automaticamente um aplicativo existente sem estado.

Um servidor de produção ainda pode depender de workspaces em memória, roteamento sticky, credenciais vinculadas à sessão, streams de longa duração ou interações iniciadas pelo servidor. Este guia foca em encontrar e substituir essas dependências.

Para um passo a passo mais introdutório de implementação, leia How to Create an MCP Server for Claude Code antes de iniciar a migração.

Quem precisa migrar?

O nível de esforço depende de como o MCP é usado no seu sistema.

Um servidor local que não preserva estado entre solicitações pode exigir apenas uma atualização do SDK e testes de compatibilidade.

Uma implantação remota usando sessões, OAuth, streaming ou solicitações iniciadas pelo servidor requer uma migração em etapas.

O que mudou no MCP 2026-07-28?

1. Audite a implementação existente

Antes de atualizar, procure no cliente, servidor, gateway e configuração de implantação por suposições do protocolo antigo.

Mcp-Session-Id
initialize
notifications/initialized
sessionId
ctx.sessionId
extra.sessionId
sticky_session
sticky-session
elicitation/create
sampling/createMessage
roots/list
resources/subscribe
resources/unsubscribe
logging/setLevel
tasks/result
tasks/list
Last-Event-ID

Em seguida, responda às seguintes perguntas:

1. O servidor rejeita chamadas até a inicialização ser concluída?
2. Um ID de sessão seleciona um usuário, credencial, workspace ou conversa?
3. Outra instância do servidor consegue continuar um workflow iniciado pela primeira?
4. O balanceador de carga exige afinidade de sessão?
5. Uma ferramenta executa um efeito colateral antes de solicitar confirmação?
6. O gateway analisa o corpo para identificar o método ou ferramenta?
7. As credenciais OAuth são armazenadas sem o authorization server emissor?
8. O cliente depende de reconexão SSE ou redelivery de mensagens?
9. As listas de ferramentas ou recursos variam por conexão?
10. Quais recursos obsoletos ainda recebem tráfego de produção?

Não remova Mcp-Session-Id até entender o que o aplicativo armazena por trás dele.

Um servidor que remove o cabeçalho, mas mantém o estado na memória local pode funcionar durante o desenvolvimento e falhar intermitentemente quando as solicitações forem distribuídas por várias instâncias.

2. Substitua o estado oculto de sessão

O MCP 2026-07-28 remove sessões no nível do protocolo, não o estado do aplicativo.

O estado necessário entre chamadas deve usar um dos três padrões.

Identificadores explícitos

Retorne um identificador emitido pelo servidor a partir de uma ferramenta e exija-o em chamadas posteriores.

{
  "resultType": "complete",
  "content": [
    {
      "type": "text",
      "text": "Workspace created."
    }
  ],
  "structuredContent": {
    "workspaceHandle": "ws_7f93a2"
  }
}

Uma solicitação posterior passa o identificador como argumento comum:

{
  "name": "update_workspace",
  "arguments": {
    "workspaceHandle": "ws_7f93a2",
    "status": "approved"
  }
}

Isso torna a dependência visível no contrato da ferramenta e permite que qualquer instância compatível do servidor processe a solicitação.

Armazenamento compartilhado

Use um banco de dados, cache distribuído, object store ou sistema de tarefas duráveis quando:

• vários workers precisarem do mesmo estado;
• o workflow deva sobreviver a uma reinicialização;
• o estado seja grande demais para um identificador;
• o workflow dure mais do que uma única solicitação;
• comportamento transacional ou de uso único seja necessário.

requestState protegido

MRTR pode retornar um valor opaco requestState que o cliente ecoa ao repetir a solicitação original.

Como o valor passa pelo cliente, proteja-o com um HMAC ou criptografia autenticada. Vincule-o ao principal autenticado, à operação original, a parâmetros importantes, ao tempo de expiração e a um nonce quando precisar de proteção contra replay.

Nunca confie em um valor requestState não assinado apenas porque o cliente o devolveu sem alterações.

3. Adote solicitações auto-contidas e discovery

As solicitações modernas MCP incluem contexto do protocolo em _meta.

Uma chamada de ferramenta via HTTP com streaming pode ser assim:

POST /mcp HTTP/1.1
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: search
Content-Type: application/json
Authorization: Bearer <token>
{
  "jsonrpc": "2.0",
  "id": "req-101",
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "stateless MCP migration"
    },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "example-client",
        "version": "2.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {
        "elicitation": {}
      }
    }
  }
}

Servidores voltados ao novo protocolo devem implementar server/discover, que divulga versões suportadas, capacidades e identidade do servidor. Clientes podem chamá-lo antes de outra operação ou usá-lo para determinar se um fallback legado é necessário.

Leia a documentação oficial de server/discover para o contrato de resposta.

Negociação de versão no SDK TypeScript

Atualizar o SDK TypeScript por si só não muda automaticamente um cliente para o novo protocolo.

Um cliente usando o SDK v2 deve optar explicitamente:

const client = new Client(
  {
    name: "my-client",
    version: "1.0.0"
  },
  {
    versionNegotiation: {
      mode: "auto"
    }
  }
);

await client.connect(transport);

No modo automático, o SDK sonda com server/discover e pode fazer fallback para o fluxo de inicialização antigo quando alcançar um servidor legado.

Equipes ainda usando @modelcontextprotocol/sdk v1 devem primeiro seguir o guia de migração do SDK TypeScript v1 para v2. Equipes já usando v2 devem usar o guia de suporte ao protocolo 2026-07-28.

4. Substitua solicitações iniciadas pelo servidor por MRTR

Implementações anteriores do MCP podiam enviar solicitações como elicitation/create, sampling/createMessage ou roots/list do servidor para o cliente.

O novo protocolo substitui esse modelo por Multi Round-Trip Requests.

O fluxo é:

1. O cliente envia a solicitação original.
2. O servidor retorna resultType: "input_required".
3. O cliente coleta as informações ou aprovações solicitadas.
4. O cliente repete a operação original usando um novo ID JSON-RPC.
5. A nova tentativa inclui inputResponses e o requestState original.
6. O servidor conclui a solicitação ou inicia outra rodada.

Exemplo de resposta:

{
  "jsonrpc": "2.0",
  "id": "delete-1",
  "result": {
    "resultType": "input_required",
    "inputRequests": {
      "confirm_delete": {
        "method": "elicitation/create",
        "params": {
          "mode": "form",
          "message": "Delete project project_123?",
          "requestedSchema": {
            "type": "object",
            "properties": {
              "confirmed": {
                "type": "boolean"
              }
            },
            "required": ["confirmed"]
          }
        }
      }
    },
    "requestState": "protected-expiring-state"
  }
}

O cliente repete a operação original:

{
  "jsonrpc": "2.0",
  "id": "delete-2",
  "method": "tools/call",
  "params": {
    "name": "delete_project",
    "arguments": {
      "projectId": "project_123"
    },
    "inputResponses": {
      "confirm_delete": {
        "action": "accept",
        "content": {
          "confirmed": true
        }
      }
    },
    "requestState": "protected-expiring-state"
  }
}

Uma implementação MRTR de produção deve definir:

• número máximo de rodadas;
• expiração de request-state;
• comportamento de cancelamento e rejeição;
• validação do schema de resposta;
• verificações de autorização em cada nova tentativa;
• proteção contra replay;
• idempotência para efeitos colaterais;
• comportamento quando um cliente não suporta a capacidade solicitada.

Evite concluir uma compra, exclusão, débito de crédito ou escrita externa antes de retornar input_required.

Use uma operação em estágios ou uma chave de idempotência para que novas tentativas não dupliquem a ação. Consulte a especificação MRTR oficial para o modelo completo de interação.

5. Atualize gateways, cache e autorização

As mudanças de infraestrutura são estreitamente relacionadas e devem ser testadas em conjunto.

Valide cabeçalhos de roteamento MCP

Solicitações POST via HTTP com streaming agora incluem:

• MCP-Protocol-Version
• Mcp-Method
• Mcp-Name

Esses cabeçalhos permitem que gateways roteiem, meçam, autorizem e apliquem rate limit ao tráfego sem analisar cada corpo JSON.

Eles podem dar suporte a controles como:

• limites de taxa específicos por ferramenta;
• políticas separadas para métodos de listagem e de execução;
• pools de workers dedicados para ferramentas caras;
• acesso restrito a operações de alto risco;
• métricas de latência e erro por ferramenta;
• atribuição de custos de infraestrutura.

Os valores ainda são fornecidos pelo cliente. Compare-os com o corpo JSON-RPC antes de aplicar a política.

Uma solicitação não deve poder declarar uma ferramenta de baixo risco em Mcp-Name ao invocar uma ferramenta diferente no corpo. Inconsistências entre cabeçalho e corpo devem ser rejeitadas e registradas.

Use chaves de cache cientes de autorização

O novo protocolo adiciona ttlMs e cacheScope a resultados cacheáveis incluindo:

• tools/list
• prompts/list
• resources/list
• resources/templates/list
• resources/read

Uma chave de cache normalmente deve incluir:

protocol version
server identity
method
request parameters
authenticated principal or tenant
authorization scope
cacheScope
server configuration version

Não reutilize uma entrada de cache privada entre usuários ou locatários apenas porque o TTL não expirou.

A ordenação determinística de ferramentas também importa. Um catálogo estável evita misses de cache desnecessários e pode melhorar o reaproveitamento de cache de prompt do modelo quando definições de ferramentas são inseridas nos prompts.

Reforce o tratamento do emissor (issuer) no OAuth

Durante a migração de autorização:

• valide um valor iss retornado contra o emissor registrado para o fluxo;
• indexe as credenciais do cliente armazenadas pelo emissor;
• nunca reutilize credenciais com outro authorization server;
• defina um application_type apropriado durante o DCR;
• prepare novas integrações para Client ID Metadata Documents.

Dynamic Client Registration permanece disponível para compatibilidade retroativa, mas está obsoleto como abordagem preferida de registro.

6. Migre notificações, Tasks e recursos obsoletos

O caminho antigo de notificações via HTTP GET e o fluxo resources/subscribe ou resources/unsubscribe foram substituídos por subscriptions/listen.

Clientes abrem um stream de resposta POST de longa duração e optam pelas categorias de notificação necessárias. Notificações de progresso e log específicas por solicitação permanecem anexadas ao stream de resposta da solicitação que descrevem.

Para implantações com múltiplas instâncias, use um barramento de eventos compartilhado quando notificações geradas em uma instância precisarem alcançar uma assinatura conectada a outra.

Extensão Tasks

O trabalho de longa duração saiu do protocolo core experimental e foi para:

io.modelcontextprotocol/tasks

A extensão usa:

• tasks/get para polling;
• tasks/update para atualizações de cliente para servidor;
• identificadores de tarefas duráveis;
• subscriptions/listen para atualizações opt-in.

Os padrões antigos tasks/result e tasks/list não devem ser carregados para uma nova implementação.

Recursos obsoletos

Os seguintes recursos estão obsoletos:

A funcionalidade obsoleta permanece disponível durante o período de desativação, mas novas implementações não devem adotá-la. A política de ciclo de vida do MCP prevê um período mínimo de doze meses; isso não significa que cada recurso tenha a mesma data de remoção confirmada.

Revise o registro de recursos obsoletos oficial antes de definir um prazo de aposentadoria.

7. Execute a migração com segurança

Não altere clientes, servidores, gateways, cache e autorização em uma única versão sem observabilidade.

Ordem de migração recomendada

1. Levante inventário de versões de protocolo, SDKs, sessões, tráfego SSE, clientes DCR e métodos obsoletos.
2. Atualize SDKs em ambientes não produtivos.
3. Adicione server/discover e negociação de versão.
4. Substitua dependências ocultas de sessão.
5. Implemente e proteja MRTR.
6. Adicione cabeçalhos de roteamento validados e caches com escopo.
7. Teste limites de emissor na autorização.
8. Faça canary do protocolo moderno ao lado do caminho legado.
9. Aposente o comportamento antigo somente após revisar a telemetria.

Compatibilidade durante o canary

Modern client + modern server
→ Use MCP 2026-07-28

Modern client + legacy server
→ Probe and fall back when supported

Legacy client + dual-version server
→ Continue on the legacy path

Unsupported combination
→ Return a clear protocol-version error

O lançamento de uma nova especificação MCP não é uma troca de toda a comunidade. Clientes, servidores, SDKs e plataformas hospedadas migrarão em velocidades diferentes.

Telemetria a registrar

Solicitações bem-sucedidas one-shot de tools/call não bastam para medir a migração. Um workflow que expira repetidamente, solicita entrada desnecessária ou duplica uma escrita externa continua sendo uma falha em produção.

Como a CometAPI se encaixa em uma arquitetura MCP

MCP não substitui uma API de modelo. As duas camadas resolvem problemas de integração diferentes.

Uma arquitetura de produção típica se parece com isto:

Application or agent
        ↓
MCP clients and servers
Tools, resources, approvals, tasks
        ↓
Unified model API
GPT, Claude, Gemini, DeepSeek, and other models

MCP padroniza como agentes interagem com ferramentas e contexto. Ele não padroniza preços de modelos, credenciais de provedores, endpoints de inferência ou failover de provedores.

Essa separação torna-se especialmente útil ao migrar do recurso obsoleto Sampling. Se um servidor MCP ou o agente que o consome ainda precisar de inferência de modelo, o aplicativo pode chamar uma API de modelo diretamente em vez de depender do antigo fluxo MCP Sampling.

Quando um gateway unificado de modelos ajuda

Um gateway de modelos unificado pode reduzir o trabalho operacional quando:

• vários servidores MCP precisarem acessar diferentes provedores de modelo;
• diferentes ferramentas exigirem modelos distintos;
• equipes quiserem trocar modelos sem reescrever integrações específicas de provedor;
• credenciais, uso e faturamento precisarem ser gerenciados centralmente;
• o acesso ao modelo deva permanecer independente de mudanças no transporte MCP.

A CometAPI fornece um endpoint compatível com OpenAI que pode ser usado como a camada de acesso a modelos por trás de aplicativos MCP. Isso mantém a lógica de provedores de modelo separada das ferramentas, recursos e orquestração de tarefas do MCP.

Por exemplo, uma ferramenta MCP pode chamar um modelo através do mesmo cliente compatível com OpenAI usado em outras partes do aplicativo:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.COMETAPI_KEY,
  baseURL: "https://api.cometapi.com/v1"
});

export async function summarizeResource(content: string) {
  const response = await client.chat.completions.create({
    model: "your-selected-model",
    messages: [
      {
        role: "system",
        content: "Summarize the supplied resource clearly and concisely."
      },
      {
        role: "user",
        content
      }
    ]
  });

  return response.choices[0]?.message?.content ?? "";
}

O servidor MCP permanece responsável pelo contrato da ferramenta, autorização, estado e tratamento do resultado. O gateway de modelos lida com seleção de modelo, acesso ao provedor e respostas de inferência.

Manter essas camadas separadas oferece dois benefícios práticos:

1. Clientes e servidores MCP podem migrar para o novo protocolo sem alterar a camada de integração de modelos.
2. Provedores de modelo podem ser trocados sem redesenhar ferramentas MCP ou o comportamento de transporte.

Para mais detalhes de implementação, consulte o Quickstart da CometAPI, a documentação da API e o guia de aplicações de IA multi-modelo.

Checklist de migração do MCP 2026-07-28

Cliente

• Atualize para um SDK compatível.
• Habilite a negociação de versão moderna.
• Suporte server/discover.
• Inclua metadados de protocolo em cada solicitação.
• Trate resultType.
• Suporte ou rejeite explicitamente MRTR.
• Use um novo ID JSON-RPC para novas tentativas.
• Preserve e retorne requestState.
• Valide emissores OAuth.
• Armazene credenciais por emissor.
• Respeite dicas de cache.
• Suporte subscriptions/listen quando necessário.

Servidor

• Remova gates de inicialização de solicitações modernas.
• Remova dependências de Mcp-Session-Id.
• Implemente server/discover.
• Substitua estado oculto por identificadores ou armazenamento compartilhado.
• Retorne resultType.
• Substitua solicitações iniciadas pelo servidor por MRTR.
• Proteja requestState.
• Valide todos os inputResponses.
• Adicione idempotência para efeitos colaterais.
• Retorne listas determinísticas.
• Publique dicas de cache conservadoras.
• Migre trabalhos de longa duração para a extensão Tasks.

Gateway e infraestrutura

• Valide cabeçalhos de solicitação MCP.
• Compare cabeçalhos com o corpo da solicitação.
• Remova roteamento sticky desnecessário.
• Teste solicitações em várias instâncias.
• Partitione caches por limite de autorização.
• Adicione um barramento de notificações compartilhado quando necessário.
• Acompanhe tráfego legado e obsoleto.
• Mantenha um caminho de rollback durante o canary.

FAQ

O que é o MCP 2026-07-28?

MCP 2026-07-28 é a especificação do Model Context Protocol lançada em 28 de julho de 2026. Ela introduz um núcleo sem estado, Multi Round-Trip Requests, cabeçalhos de roteamento HTTP, resultados cacheáveis, mudanças de autorização, extensões e um ciclo de vida formal de desativação.

Mcp-Session-Id foi removido?

Sim. O novo protocolo HTTP com streaming não usa Mcp-Session-Id.

Aplicações ainda podem preservar estado através de identificadores explícitos, armazenamento compartilhado, tarefas duráveis ou valores de request-state protegidos.

O handshake de inicialização do MCP foi removido?

Sim. Solicitações modernas não exigem a troca initialize e notifications/initialized.

Servidores devem implementar server/discover, embora clientes não precisem chamá-lo antes de cada operação.

MCP sem estado significa que ferramentas não podem preservar estado?

Não. Sem estado refere-se à camada de protocolo.

Uma ferramenta ainda pode armazenar estado, mas o processamento da solicitação não deve depender de afinidade de transporte oculta ou de um processo específico do servidor.

O que é MRTR?

Multi Round-Trip Requests permitem que um servidor solicite entrada adicional do cliente ou usuário sem enviar uma solicitação iniciada pelo servidor por uma conexão bidirecional continuamente aberta.

O servidor retorna input_required, e o cliente repete a operação original com as respostas solicitadas.

HTTP+SSE foi removido imediatamente?

Não. Está obsoleto, mas não removido imediatamente.

Novos servidores devem usar HTTP com streaming, enquanto sistemas existentes devem medir e migrar o tráfego HTTP+SSE remanescente.

Clientes do SDK TypeScript v2 usam MCP 2026-07-28 automaticamente?

Não. O SDK v2 de TypeScript exige uma configuração explícita de negociação de versão para usar o protocolo moderno.

Use negociação automática quando o cliente precisar funcionar com servidores modernos e legados.

Recomendações finais

MCP 2026-07-28 torna a infraestrutura MCP remota mais fácil de escalar, rotear, armazenar em cache e observar. O principal risco de migração não é simplesmente a remoção de um cabeçalho ou handshake. É o estado de aplicativo oculto e a lógica de interação que ainda podem depender deles.

Antes de implantar o novo protocolo:

Encontre toda dependência de inicialização e Mcp-Session-Id.

1. Passe o estado necessário para identificadores explícitos ou armazenamento compartilhado.
2. Implemente MRTR com expiração, proteção contra replay e idempotência.
3. Valide cabeçalhos MCP contra o corpo JSON-RPC.
4. Partitione caches por locatário e escopo de autorização.
5. Reforce a validação do emissor no OAuth.
6. Meça métodos obsoletos e tráfego de transporte legado.
7. Faça canary dos caminhos de protocolo moderno e legado antes da aposentadoria.

Trate a migração como uma mudança de infraestrutura, não como uma simples atualização de SDK.

Uma vez que a camada MCP esteja sem estado e observável, mantenha o acesso a modelos por trás de uma interface separada. Isso permite que o protocolo de ferramentas e a camada de provedores de modelo evoluam de forma independente.