MCP stateless: migrando um servidor Streamable HTTP para o modo sem sessão

O transporte Streamable HTTP do MCP (spec 2025-06-18) substituiu o antigo HTTP+SSE e trouxe uma decisão de arquitetura que muita gente ignora: você não é obrigado a manter sessão. O Mcp-Session-Id é opcional. Se o seu servidor não precisa de estado entre requests, dá pra rodar tudo _stateless_, o que simplifica escala horizontal (qualquer réplica atende qualquer request) e mata uma classe inteira de bugs de sessão órfã.

Peguei um servidor MCP stateful que eu tinha em Node/TS e migrei pra stateless. Aqui está o que aconteceu na prática.

O que a spec diz (e o que muda)

No modelo stateful, o servidor devolve um Mcp-Session-Id no header da resposta do InitializeResult, e o cliente é obrigado a repetir esse header em todos os requests seguintes. A spec é clara: servidores que exigem sessão devem responder 400 Bad Request a requests sem o header (exceto o initialize), e podem devolver 404 Not Found quando a sessão expira.

No modo stateless, você simplesmente não emite o Mcp-Session-Id. Cada POST ao endpoint /mcp é autossuficiente: chega, é processado, responde. Sem cursor de sessão, sem armazenar transporte na memória.

O ponto de partida: servidor stateful

O padrão que a maioria dos exemplos usa mantém um mapa de transportes por sessão:

const transports: Record<string, StreamableHTTPServerTransport> = {};

app.post('/mcp', async (req, res) => {
  const sessionId = req.headers['mcp-session-id'] as string;
  let transport = transports[sessionId];

  if (!transport && isInitializeRequest(req.body)) {
    transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: () => randomUUID(),
      onsessioninitialized: (id) => { transports[id] = transport; },
    });
    await server.connect(transport);
  } else if (!transport) {
    return res.status(400).json({ error: 'sessão inválida' });
  }

  await transport.handleRequest(req, res, req.body);
});

Esse transports global é exatamente o que te prende a uma instância. Ele é a coisa que quero eliminar.

A versão stateless

A mudança central é sessionIdGenerator: undefined. Com isso o SDK não emite Mcp-Session-Id, e eu crio um transporte novo por request, sem cache:

app.post('/mcp', async (req, res) => {
  try {
    const server = buildServer(); // instância nova por request
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined, // <- stateless
    });

    res.on('close', () => {
      transport.close();
      server.close();
    });

    await server.connect(transport);
    await transport.handleRequest(req, res, req.body);
  } catch (err) {
    if (!res.headersSent) {
      res.status(500).json({
        jsonrpc: '2.0',
        error: { code: -32603, message: 'Internal error' },
        id: null,
      });
    }
  }
});

Repare que instanciei server e transport dentro do handler. Foi aqui que quebrou na primeira tentativa: eu tinha deixado uma instância única do McpServer reutilizada entre requests, e o SDK reclamou de transporte já conectado. Em stateless, cada request é uma vida completa: cria, conecta, responde, fecha no res.on('close').

Onde a auth muda de lugar

Esse é o ponto que mais dói. No modo stateful, era comum autenticar uma vez no initialize e associar o usuário ao sessionId. Sem sessão, isso some. Toda request precisa carregar sua própria credencial, tipicamente um Authorization: Bearer.

Movi a autenticação pra um middleware antes do handler MCP:

function authPerRequest(req, res, next) {
  const auth = req.headers['authorization'];
  if (!auth?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'token ausente' });
  }
  const user = verifyToken(auth.slice(7)); // valida a cada request
  if (!user) return res.status(401).json({ error: 'token inválido' });
  req.user = user;
  next();
}

app.post('/mcp', authPerRequest, async (req, res) => { /* ... */ });

E aí buildServer() passa a receber o contexto do usuário para escopar as tools daquele request. Sem essa mudança, você teria um servidor stateless autenticando ninguém, um belo buraco de segurança.

O que quebra nos clientes

Clientes bem-comportados não deveriam se importar: se o servidor não devolve Mcp-Session-Id, o cliente simplesmente não o reenvia. Mas topei com dois problemas:

• Requisições GET para SSE: no stateless puro eu não abro streams servidor-para-cliente. A spec permite responder 405 Method Not Allowed ao GET no endpoint. Clientes que esperavam abrir um canal SSE passivo recebem 405. Se seu servidor manda notificações não solicitadas, stateless não serve.
• Reconexão com Last-Event-ID: resumability depende de IDs únicos por stream (por sessão, ou por cliente quando não há sessão). Sem sessão e sem SSE, resumability sai de cena. Streams interrompidos viram request perdido.

Quando vale (e quando não)

Vale quando suas tools são request/response puro: consulta, cálculo, chamada a API externa. Ganha escala trivial e menos código.

Não vale se você precisa de notificações server-to-client, progresso em streaming de tarefas longas, ou estado acumulado durante a conversa. Nesses casos a sessão existe por um motivo. Não force stateless só pela moda: eu mantive stateful num servidor de tarefas longas justamente porque o progresso via SSE era o produto.

Lembre também das exigências de segurança da spec, independentes do modo: validar o header Origin contra DNS rebinding e, em local, bindar só em 127.0.0.1.

Fonte: MCP Specification — Streamable HTTP Transport (stateless mode)