MCP Streamable HTTP: cómo crear servidores remotos sin copiar tutoriales antiguos

La keyword principal es `MCP Streamable HTTP`; la intención es técnica y de implementación: un developer busca exponer un servidor MCP por URL para varios clientes sin confundir el transporte remoto actual con el viejo HTTP+SSE de dos endpoints.

El punto práctico es que HTTP permite TLS, un balanceador, observabilidad y una ruta estable como `https://mcp.ejemplo.com/mcp`. El coste es que ahora tus errores de red, CORS, autenticación, buffering de proxies y despliegue pasan a formar parte del contrato que el cliente debe soportar.

Código: endpoint remoto moderno en TypeScript

La API actual del SDK TypeScript v2 usa una factory por petición. La factory crea un `McpServer` para el llamador actual; los pools y caches viven fuera, pero la identidad y el servidor no se comparten entre requests. Este ejemplo usa un handler web-standard y después lo adapta a Node.

import { createMcpHandler, McpServer } from "@modelcontextprotocol/server";
import { toNodeHandler } from "@modelcontextprotocol/node";
import * as z from "zod/v4";

const handler = createMcpHandler(({ authInfo }) => {
  const actorId = authInfo?.clientId;
  if (!actorId) throw new Error("authenticated caller required");

  const server = new McpServer({ name: "reports", version: "1.0.0" });
  server.registerTool(
    "get-report",
    {
      description: "Read a report owned by the authenticated caller",
      inputSchema: z.object({ reportId: z.string().uuid() }),
    },
    async ({ reportId }) => {
      const report = await reports.findOwnedBy(reportId, actorId);
      if (!report) return { content: [{ type: "text", text: "Not found" }], isError: true };
      return { content: [{ type: "text", text: report.summary }] };
    },
  );
  return server;
});

export const mcp = toNodeHandler(handler); // app.all("/mcp", mcp)

Protege el endpoint antes de la primera tool

Valida `Origin` en toda conexión entrante; la especificación lo exige para defender servidores locales frente a DNS rebinding. En local, escucha en `127.0.0.1`, no en `0.0.0.0`. El SDK recomienda además validar `Host` delante del handler. CORS no sustituye esa validación: CORS gobierna qué puede leer un navegador; no decide si tu servidor procesa una petición hostil.

Para un servidor remoto protegido, implementa OAuth 2.1 como resource server. El cliente presenta `Authorization: Bearer`; el token no va en query string y se valida contra la audiencia del recurso MCP concreto. La especificación MCP requiere Protected Resource Metadata cuando soportas autorización y permite que una respuesta `401` o `403` explique scopes mínimos mediante `WWW-Authenticate`.

Mantén las herramientas con capacidades pequeñas. Separa `read_report` de `delete_report`; aplica límite por actor y tool; valida IDs y rangos en backend; registra un request ID. Un token válido no convierte cualquier argumento en legítimo. Los schemas de MCP evitan formatos absurdos, pero no sustituyen permisos de negocio ni aislamiento multi-tenant.

La compatibilidad no debe incluir HTTP+SSE por nostalgia. Úsala solo para usuarios identificados y con una ruta aislada. Un nuevo deployment debería arrancar con un único `/mcp` moderno, documentación que nombra la revisión de protocolo y una matriz de clientes probada en CI.

Escala sin convertir SSE en estado

Un handler por request y herramientas idempotentes hacen que escalar horizontalmente sea bastante normal: cualquier réplica puede atender el siguiente POST. Para una tarea larga, devuelve un identificador de trabajo y ofrece una tool de consulta o usa las utilidades de tareas de la versión que soportes. No dependas de que la misma conexión TCP, pod o stream permanezca vivo.

SSE sí exige cuidado operacional. Desactiva buffering del proxy (`X-Accel-Buffering: no` cuando aplique), revisa timeouts de idle y propaga desconexión para cancelar cálculo desperdiciado. Pero no abras SSE por defecto: para una lectura rápida, JSON reduce recursos y hace observabilidad más simple. Escoge streaming cuando hay progreso, pasos intermedios o latencia real que explicar.

Registra protocolo, method, tool name, actor pseudonimizado, status, latencia, bytes, tipo de respuesta JSON/SSE y motivo de denegación. No metas argumentos completos ni resultados sensibles en las trazas. Es suficiente para detectar una tool lenta o un cliente antiguo sin convertir logs en una fuga de datos.

Checklist de despliegue

• El endpoint `/mcp` está detrás de TLS y no comparte una ruta ambigua con una API pública genérica.
• El runtime valida Origin y Host; el proceso local se liga a loopback cuando no debe ser remoto.
• OAuth valida firma, issuer, expiración, audiencia del recurso y scopes; no acepta tokens por query string.
• Cada tool deriva tenant y actor del contexto autenticado y comprueba permisos en backend.
• Cliente y servidor soportan JSON y SSE por request; existe cancelación y el proxy no bufferiza streams.
• Los headers MCP requeridos coinciden con el body y se rechazan mismatches en borde y servidor.
• La política de compatibilidad enumera versiones, clientes, ruta legacy si existe y fecha de retirada.
• Hay tests de contrato, seguridad, aislamiento de tenants, cancelación y despliegue tras un proxy real.