MCP: "Unsupported protocol version" ao conectar, como resolver com uma ponte local
Voltar para o Blog
Artigoverboo codemcptutorialdev tools

MCP: "Unsupported protocol version" ao conectar, como resolver com uma ponte local

Mafra19 de novembro de 20268 min de leitura

O sintoma é silencioso de um lado e barulhento do outro. O cliente MCP conecta, o painel mostra o servidor como ativo, e a lista de ferramentas volta vazia. No log do servidor, um 400 seco, sem stack trace.

Aconteceu com a gente ao ligar o MCP do blog na Verboo Code. O cliente falava uma revisão do protocolo MCP, o servidor exigia outra. Não era bug de nenhum dos dois: o protocolo prevê que a negociação de versão pode falhar, e define exatamente o que cada ponta deve fazer quando falha.

A saída que a gente escolheu não foi forkar o cliente nem reescrever o servidor. Foi uma ponte pequena, local, no meio do caminho. Este artigo mostra por que ela funciona e como montar a sua.

Por que a revisão do protocolo MCP derruba a conexão?

Porque a negociação de versão acontece na primeira mensagem e não é consultiva. O cliente manda initialize com a versão que suporta, o servidor responde com a versão dele, e se o cliente não suportar a resposta, o comportamento correto é desconectar.

A especificação é direta nesses pontos:

  • Se o servidor suporta a versão pedida, ele deve responder com a mesma versão. Caso contrário, deve responder com outra versão que suporte, de preferência a mais recente dele.
  • Se o cliente não suporta a versão devolvida pelo servidor, ele deve desconectar.
  • Em HTTP, o cliente deve mandar o header MCP-Protocol-Version em toda requisição depois do initialize, e o servidor deve responder 400 quando a versão é inválida ou não suportada.

O erro que aparece nesse caso costuma ser este, com a lista de versões que o servidor aceita:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Unsupported protocol version",
    "data": {
      "supported": ["2025-06-18"],
      "requested": "2025-03-26"
    }
  }
}

Guarde esse data.supported. É a revisão que a ponte vai precisar usar do lado de cima.

Como descobrir em qual revisão cada ponta está?

Pelo handshake, sem adivinhar. A primeira mensagem de qualquer sessão MCP é initialize, e as duas versões aparecem nela. Dá para ver isso com um curl, antes de culpar o cliente:

curl -s https://seu-servidor/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "probe", "version": "0.0.0" }
    }
  }'

Se a resposta vier com um protocolVersion diferente do que você mandou, o servidor está devolvendo a revisão que ele fala. Se a resposta trouxer o header Mcp-Session-Id, anote: ele vai ser obrigatório em todas as chamadas seguintes.

SintomaCausa provávelOnde olhar
Servidor aparece conectado, lista de ferramentas vaziaCliente não suporta a revisão devolvida no handshakeResposta do initialize e o erro -32602
400 em toda chamada depois do handshakeHeader MCP-Protocol-Version ausente ou erradoRequisição HTTP que o cliente monta
400 já no primeiro POSTServidor exige sessão e a chamada chegou sem Mcp-Session-IdHeaders da resposta do initialize
404 em chamadas que antes funcionavamSessão expirou do lado do servidorHeader Mcp-Session-Id da chamada

Ponte local, fork do cliente ou troca de servidor?

Existem quatro caminhos. A ordem abaixo é a de menor custo para maior custo, e a ponte fica no meio de propósito: ela resolve o caso em que você não controla nenhuma das duas pontas.

CaminhoQuando faz sentidoCusto
Atualizar o clienteA revisão nova já está disponível na versão que você usaMenor. Um update e um restart.
Ponte localO servidor exige uma revisão que o cliente não fala e você não quer manter um forkUm script pequeno, sem fork.
Atualizar o servidorVocê controla o servidor e o cliente é fixoMédio. Mexe em algo que já está no ar.
Forkar o clienteQuase nuncaAlto. Você herda a manutenção do fork para sempre.

A ponte é um processo local que fala stdio com o cliente e HTTP com o servidor. O cliente acha que está falando com um servidor MCP comum. O servidor recebe requisições na revisão que ele exige. Nenhum dos dois sabe que existe um intermediário.

Como montar a ponte em quatro passos

Primeiro, declare a ponte como um servidor stdio no .mcp.json do projeto. O formato é o mesmo de qualquer servidor local: command, args e env.

{
  "mcpServers": {
    "blog": {
      "type": "stdio",
      "command": "node",
      "args": ["/caminho/ponte-mcp.mjs"],
      "env": {
        "MCP_UPSTREAM": "https://seu-servidor/mcp",
        "MCP_UPSTREAM_VERSION": "2025-06-18"
      }
    }
  }
}

Segundo, leia o JSON-RPC que chega pelo stdin, uma mensagem por linha. Terceiro, repasse cada mensagem por POST para o endpoint com os headers certos. Quarto, devolva a resposta no stdout e guarde o Mcp-Session-Id para as próximas chamadas.

O script abaixo faz os quatro passos. Ele é a ponte inteira, sem dependência além do node:

#!/usr/bin/env node
// ponte stdio -> Streamable HTTP
const UPSTREAM = process.env.MCP_UPSTREAM;
const VERSION = process.env.MCP_UPSTREAM_VERSION;

let sessionId = null;
let clientVersion = null;
let buf = "";

process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => {
  buf += chunk;
  let i;
  while ((i = buf.indexOf("\n")) !== -1) {
    const line = buf.slice(0, i).trim();
    buf = buf.slice(i + 1);
    if (line) forward(line);
  }
});

async function forward(raw) {
  const msg = JSON.parse(raw);

  // guarda a revisao que o cliente pediu
  if (msg.method === "initialize") {
    clientVersion = msg.params?.protocolVersion ?? null;
  }

  const headers = {
    "Content-Type": "application/json",
    Accept: "application/json, text/event-stream",
    "MCP-Protocol-Version": VERSION,
  };
  if (sessionId) headers["Mcp-Session-Id"] = sessionId;

  const res = await fetch(UPSTREAM, { method: "POST", headers, body: raw });

  const sid = res.headers.get("mcp-session-id");
  if (sid) sessionId = sid;

  if (res.status === 202 || res.status === 204) return;

  const type = res.headers.get("content-type") || "";
  if (type.includes("text/event-stream")) {
    const reader = res.body.getReader();
    const dec = new TextDecoder();
    let rest = "";
    for (;;) {
      const { value, done } = await reader.read();
      if (done) break;
      rest += dec.decode(value, { stream: true });
      let j;
      while ((j = rest.indexOf("\n\n")) !== -1) {
        const event = rest.slice(0, j);
        rest = rest.slice(j + 2);
        for (const l of event.split("\n")) {
          if (l.startsWith("data:")) emit(l.slice(5).trim());
        }
      }
    }
    return;
  }

  emit(await res.text());
}

function emit(text) {
  if (!text) return;
  let out = text.trim();

  // o cliente desconecta se a revisao devolvida nao for a que ele pediu
  try {
    const msg = JSON.parse(out);
    if (msg.result && clientVersion && msg.result.protocolVersion) {
      msg.result.protocolVersion = clientVersion;
      out = JSON.stringify(msg);
    }
  } catch {}

  process.stdout.write(out + "\n");
}

Com a ponte no ar, abra a Verboo Code e digite /mcp. O servidor deve aparecer como conectado, com a contagem de ferramentas. Se aparecer conectado e vazio, o problema não é mais de transporte: é de capabilities.

O que a ponte precisa preservar?

A parte que quebra na segunda-feira não é o initialize, são os detalhes que vêm depois. Estes são os que mais custaram tempo na nossa versão:

  • O Accept precisa listar os dois tipos. O cliente e a ponte devem aceitar application/json e text/event-stream, porque o servidor pode escolher responder com qualquer um dos dois.
  • A sessão vai em toda chamada. Depois que o servidor devolve Mcp-Session-Id no initialize, toda requisição seguinte precisa repetir o header. Servidor que exige sessão costuma responder 400 quando ele falta.
  • 404 com sessão significa sessão morta. O certo é descartar o id e mandar um novo initialize sem sessão, não repetir a chamada com o id antigo.
  • SSE não fecha antes da resposta. Quando o servidor responde em stream, cada evento data: é uma mensagem JSON-RPC. Repasse todos e não encerre o stream antes do evento que traz a resposta da requisição.
  • A revisão devolvida precisa ser a que o cliente pediu. Se a ponte repassa o protocolVersion do servidor sem reescrever, o cliente desconecta no handshake. É por isso que a função emit do script acima reescreve esse campo.

O que a ponte não deve fazer é traduzir semântica. Se a revisão nova mudou o formato do resultado de uma ferramenta, o campo de erro de um recurso ou o fluxo de autorização, reescrever o envelope só empurra o problema para a primeira chamada real. Ponte serve para diferença de envelope e header, não para diferença de contrato.

Quando a ponte não é a resposta?

Três casos em que vale parar antes de escrever o script:

  • A diferença é de contrato. Se o formato de tools/call mudou, a ponte vira uma camada de compatibilidade que você vai manter para sempre. Atualize a ponta que você controla.
  • A diferença é de transporte. Servidor antigo em SSE contra cliente novo em Streamable HTTP não se resolve com header. Precisa de uma adaptação de transporte de verdade, e aí é melhor usar um SDK que já faça isso.
  • A autenticação mudou. Se a revisão nova exige um fluxo OAuth que o cliente não implementa, a ponte precisaria carregar o token por você. Isso deixa de ser ponte e vira um problema de credencial no meio do caminho.

Nosso caso era o mais simples dos três: mesma semântica, envelope e header diferentes. Uma tarde de trabalho, zero fork, e o cliente voltou a listar ferramentas sem saber que havia alguém no meio.

Se o seu servidor MCP responde em uma revisão que o cliente não fala, o caminho é o mesmo: descubra as duas versões no initialize, escreva a ponte, registre no .mcp.json e confira com /mcp. A Verboo Code aceita servidores stdio, sse e http no mesmo arquivo, então a ponte entra como qualquer outro servidor local. Roda o mesmo handshake e vê qual revisão cada ponta fala.

Gostou deste artigo?
Compartilhe conhecimento com sua rede.
// Leia também

Artigos relacionados