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-Versionem toda requisição depois doinitialize, e o servidor deve responder400quando 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.
| Sintoma | Causa provável | Onde olhar |
|---|---|---|
| Servidor aparece conectado, lista de ferramentas vazia | Cliente não suporta a revisão devolvida no handshake | Resposta do initialize e o erro -32602 |
400 em toda chamada depois do handshake | Header MCP-Protocol-Version ausente ou errado | Requisição HTTP que o cliente monta |
400 já no primeiro POST | Servidor exige sessão e a chamada chegou sem Mcp-Session-Id | Headers da resposta do initialize |
404 em chamadas que antes funcionavam | Sessão expirou do lado do servidor | Header 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.
| Caminho | Quando faz sentido | Custo |
|---|---|---|
| Atualizar o cliente | A revisão nova já está disponível na versão que você usa | Menor. Um update e um restart. |
| Ponte local | O servidor exige uma revisão que o cliente não fala e você não quer manter um fork | Um script pequeno, sem fork. |
| Atualizar o servidor | Você controla o servidor e o cliente é fixo | Médio. Mexe em algo que já está no ar. |
| Forkar o cliente | Quase nunca | Alto. 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
Acceptprecisa listar os dois tipos. O cliente e a ponte devem aceitarapplication/jsonetext/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-Idnoinitialize, toda requisição seguinte precisa repetir o header. Servidor que exige sessão costuma responder400quando ele falta. 404com sessão significa sessão morta. O certo é descartar o id e mandar um novoinitializesem 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
protocolVersiondo servidor sem reescrever, o cliente desconecta no handshake. É por isso que a funçãoemitdo 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/callmudou, 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.

![[CC] travado e sem resposta por 15 minutos: como destravar](/_next/image?url=https%3A%2F%2Fstorage.googleapis.com%2Fverboo-landing-page%2Fblog-uploads%2F1783232445352-verboo-code-cover.png&w=3840&q=75)