mcp-helmet

Produktionsreife Middleware für MCP-Server. Authentifizierung, Sitzungen, Health-Checks, geordnetes Herunterfahren, Transport-Ergonomie. Kombinierbare Middleware, die sich in ihrem Geist bei Express' helmet bedient.

mcp-helmet erweitert das offizielle @modelcontextprotocol/sdk um Funktionen, die dort fehlen: automatische Transport-Erkennung, Content-Wrapping, Health-Checks, geordnetes Herunterfahren, Sitzungsverwaltung und Authentifizierungs-Middleware. Ein Paket. Kombinierbar. Lassen Sie weg, was Sie nicht benötigen. Entwickeln Sie in Minuten statt Tagen von „Hello World“ bis zur Produktion.

npm install mcp-helmet @modelcontextprotocol/sdk zod

Peer-Abhängigkeiten: @modelcontextprotocol/sdk ^1.29.0, zod ^3.22.0 oder ^3.25 (v4). zod-to-json-schema ist eine optionale Peer-Abhängigkeit für Zod v3-Benutzer.

Schnellstart

Der schnellste Weg ist der Scaffolder:

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

Sie erhalten einen funktionierenden MCP-Server mit healthCheck(), gracefulShutdown(), optionaler Authentifizierung, einem mehrstufigen Dockerfile und einer typgeprüften tsconfig. Verwenden Sie Flags, um Teile zu überspringen (--no-docker, --no-health usw.) oder passen Sie diese nachträglich an.

Oder binden Sie es manuell ein:

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();

Das ist alles. Keine Transport-Verkabelung, kein Aufbau von Content-Arrays, keine Signal-Handler. Starten Sie es:

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

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

Der gleiche Code, beide Modi.

Authentifizierung in 6 Zeilen

Bearer-Token-Verifizierung, wobei der verifizierte Principal innerhalb jedes Tool-Handlers verfügbar ist:

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();

Die Signatur des Tool-Handlers mit einem Argument bleibt gleich — getAuthContext() liest aus AsyncLocalStorage, sodass es von jeder Tiefe in der Async-Kette funktioniert.

Warum existiert dies?

Wir haben 30 MCP-Server in der Produktion und 320 GitHub-Issues in den offiziellen SDKs geprüft. Drei Muster traten immer wieder auf:

1. Jeder Server schreibt dieselben 20-40 Zeilen Setup neu. Transportauswahl, Content-Wrapping, Fehlerformatierung, Signalbehandlung. Das SDK liefert Ihnen die Bausteine; dies liefert Ihnen das Haus.

2. Server, die lokal funktionieren, scheitern in der Produktion. Docker-Container beenden sich nach einer Antwort, Kubernetes-Pods verlieren Sitzungen, kein Health-Check für Load Balancer zum Testen. 52 % der Remote-MCP-Endpunkte in einer aktuellen Umfrage waren tot.

3. Niemand versteht die Authentifizierung. „Wie greife ich innerhalb meines Tools auf das Bearer-Token zu?“ ist die am häufigsten gestellte Frage in beiden SDK-Repos.

mcp-helmet löst diese Probleme mit kombinierbarer Middleware, die das SDK erweitert, ohne es zu ersetzen.

Status

v0.1.0-alpha — funktionsvollständig. Aktuell enthalten:

• ✅ createServer() mit automatischem Content-Wrapping (String, Objekt, Content[])

• ✅ Automatische Transport-Erkennung über die Umgebungsvariable MCP_TRANSPORT

• ✅ Zod v3 + v4 Kompatibilitäts-Shim

• ✅ Kombinierbares Middleware-System (server.use(mw))

• ✅ healthCheck() Middleware

• ✅ gracefulShutdown() Middleware

• ✅ bearerAuth() und apiKeyAuth() Middleware mit AsyncLocalStorage-basiertem getAuthContext()

• ✅ rateLimiter() Middleware (gleitendes Fenster, IP- oder Schlüssel-basiert, Standard 429-Header)

• ✅ npx mcp-helmet init CLI-Scaffolder + Docker-Vorlage

v0.1.0 stabil folgt, sobald der Alpha-Zyklus über 30 Tage Nutzung in der Praxis aufweist. v0.2 steht auf der ROADMAP: Redis-basierter Sitzungsspeicher, strukturierte Logging-Middleware, Python-Portierung via FastMCP-Plugin.

Wie es sich zum offiziellen SDK verhält

mcp-helmet ist kein Fork, keine Alternative und kein Ersatz. Es ist eine Komfortschicht.

Das SDK ist eine Peer-Abhängigkeit. Sie bringen Ihre eigene Version mit. Wenn das SDK Funktionen hinzufügt, die sich überschneiden, wird die Toolkit-Middleware zu einem dünnen Durchreich-Element.

Anforderungen

• Node.js 20+

• @modelcontextprotocol/sdk ^1.29.0

• TypeScript 5.4+ (empfohlen, nicht erforderlich)

• Zod 3.22+ oder 3.25+ (v4 via zod/v4 Subpath)

Mitwirken

PRs und Issues sind willkommen. Siehe CONTRIBUTING.md für Setup-, Test- und PR-Konventionen.

Sicherheit

Siehe SECURITY.md für den verantwortungsvollen Offenlegungspfad.

Lizenz

MIT