mcp-helmet

Middleware de producción para servidores MCP. Autenticación, sesiones, comprobaciones de estado, apagado elegante, ergonomía de transporte. Middleware componible inspirado en el helmet de Express.

mcp-helmet envuelve el @modelcontextprotocol/sdk oficial con las cosas que no incluye: detección automática de transporte, envoltura de contenido, comprobaciones de estado, apagado elegante, gestión de sesiones y middleware de autenticación. Un solo paquete. Componible. Descarta lo que no necesites. Pasa de un "hola mundo" a producción en minutos, no en días.

npm install mcp-helmet @modelcontextprotocol/sdk zod

Dependencias de pares: @modelcontextprotocol/sdk ^1.29.0, zod ^3.22.0 o ^3.25 (v4). zod-to-json-schema es un par opcional para usuarios de Zod v3.

Inicio rápido

La forma más rápida es usar el generador de andamiaje:

npx mcp-helmet init my-server --transport http --auth bearer
cd my-server
npm install
npm run dev

Obtendrás un servidor MCP funcional con healthCheck(), gracefulShutdown(), autenticación opcional, un Dockerfile multietapa y un tsconfig con comprobación de tipos. Usa flags para omitir partes (--no-docker, --no-health, etc.) o personalízalo después.

O configúralo manualmente:

import { createServer } from "mcp-helmet";
import { z } from "zod";

const server = createServer({ name: "hello", version: "1.0.0" });

server.tool("greet", { name: z.string() }, async ({ name }) => {
  return `Hello, ${name}!`;
});

await server.start();

Eso es todo. Sin configuración de transporte, sin construcción de arrays de contenido, sin manejadores de señales. Ejecútalo:

# Local development (stdio, the default)
npx tsx src/index.ts

# Production (HTTP)
MCP_TRANSPORT=http PORT=3000 node dist/index.js

El mismo código, ambos modos.

Autenticación en 6 líneas

Verificación de token Bearer, con el principal verificado disponible dentro de cualquier manejador de herramientas:

import { createServer, bearerAuth, getAuthContext } from "mcp-helmet";

const server = createServer({ name: "secure", version: "1.0.0" });

server.use(bearerAuth({
  verify: async (token) => {
    const claims = await verifyJwt(token); // your call
    return { user: claims.sub, scopes: claims.scope?.split(" ") ?? [] };
  },
}));

server.tool("whoami", {}, async () => {
  const auth = getAuthContext();
  return { user: auth?.user, scopes: auth?.scopes };
});

await server.start();

La firma del manejador de herramientas de un solo argumento sigue siendo la misma: getAuthContext() lee desde AsyncLocalStorage, por lo que funciona desde cualquier profundidad en la cadena asíncrona.

Por qué existe esto

Auditamos 30 servidores MCP en producción y 320 problemas de GitHub en los SDK oficiales. Tres patrones aparecían constantemente:

1. Cada servidor reescribe las mismas 20-40 líneas de configuración. Selección de transporte, envoltura de contenido, formato de errores, manejo de señales. El SDK te da los bloques de construcción; esto te da la casa.

2. Los servidores que funcionan localmente fallan en producción. Los contenedores Docker se cierran después de una respuesta, los pods de Kubernetes pierden sesiones, no hay comprobación de estado para que los balanceadores de carga realicen sondeos. El 52% de los endpoints MCP remotos en una encuesta reciente estaban inactivos.

3. Nadie entiende la autenticación. "¿Cómo accedo al token bearer dentro de mi herramienta?" es la pregunta más frecuente en ambos repositorios de SDK.

mcp-helmet resuelve esto con middleware componible que extiende el SDK sin reemplazarlo.

Estado

v0.1.0-alpha — funcionalidad completa. Actualmente incluye:

• ✅ createServer() con envoltura automática de contenido (string, object, Content[])

• ✅ Detección automática de transporte mediante la variable de entorno MCP_TRANSPORT

• ✅ Adaptador de compatibilidad para Zod v3 + v4

• ✅ Sistema de middleware componible (server.use(mw))

• ✅ Middleware healthCheck()

• ✅ Middleware gracefulShutdown()

• ✅ Middleware bearerAuth() y apiKeyAuth() con getAuthContext() basado en AsyncLocalStorage

• ✅ Middleware rateLimiter() (ventana deslizante, basado en IP o clave, cabeceras 429 estándar)

• ✅ Generador CLI npx mcp-helmet init + plantilla Docker

La versión estable v0.1.0 llegará una vez que el ciclo alfa tenga más de 30 días de uso en el mundo real. La v0.2 está en el ROADMAP: almacenamiento de sesiones respaldado por Redis, middleware de registro estructurado, puerto a Python mediante plugin FastMCP.

Cómo se relaciona con el SDK oficial

mcp-helmet no es un fork, una alternativa ni un reemplazo. Es una capa de conveniencia.

El SDK es una dependencia de par. Tú traes tu propia versión. Si el SDK añade características que se solapan, el middleware del kit de herramientas se convierte en un paso intermedio ligero.

Requisitos

• Node.js 20+

• @modelcontextprotocol/sdk ^1.29.0

• TypeScript 5.4+ (recomendado, no obligatorio)

• Zod 3.22+ o 3.25+ (v4 mediante subruta zod/v4)

Contribución

Las PRs y los problemas son bienvenidos. Consulta CONTRIBUTING.md para conocer las convenciones de configuración, pruebas y PR.

Seguridad

Consulta SECURITY.md para conocer la ruta de divulgación responsable.

Licencia

MIT