mcp-helmet
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'
helmetbedient.
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 zodPeer-Abhängigkeiten:
@modelcontextprotocol/sdk^1.29.0,zod^3.22.0 oder ^3.25 (v4).zod-to-json-schemaist 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 devSie 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.jsDer gleiche Code, beide Modi.
Related MCP server: mcp-server-toolkit
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:
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.
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.
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()undapiKeyAuth()Middleware mit AsyncLocalStorage-basiertemgetAuthContext()✅
rateLimiter()Middleware (gleitendes Fenster, IP- oder Schlüssel-basiert, Standard 429-Header)✅
npx mcp-helmet initCLI-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.
Anliegen | Offizielles SDK | mcp-helmet |
Protokoll-Implementierung | Ja | Nein, delegiert an SDK |
Transport-Klassen | Ja | Nein, umschließt SDK-Transporte |
Tool/Ressource/Prompt-Registrierung | Ja | Ja, schlankere API |
OAuth-Server-Flows | Ja (in v2 dev) | Nein, außerhalb des Geltungsbereichs |
Bearer/API-Key-Middleware | Express-gekoppelt in v2 | Transport-agnostisch, kombinierbar |
Health-Checks | Nein | Ja, geplant |
Sitzungs-Externalisierung | Nein | Übergangslösung bis zum Upstream SEP |
Docker/Deployment-Vorlagen | Nein | Ja, geplant |
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.0TypeScript 5.4+ (empfohlen, nicht erforderlich)
Zod 3.22+ oder 3.25+ (v4 via
zod/v4Subpath)
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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
An MCP server for Arcjet - the runtime security platform that ships with your AI code.
The official MCP Server for the Mux API
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA production-ready MCP server scaffold that features built-in authentication, Docker support, and a comprehensive CI/CD release pipeline. It provides a standardized template for deploying servers with multi-transport support and configurable read-only modes.MIT
- AlicenseNot gradedqualityDmaintenanceProduction-ready MCP server starter with authentication, observability, and a plugin system for building and deploying MCP servers quickly.MIT
- AlicenseAqualityDmaintenanceA production-ready foundation for building secure, observable MCP servers with built-in authentication, rate limiting, and reference tools like database-query and semantic-search.1520 npmMIT
- AlicenseNot gradedqualityBmaintenanceA production-minded MCP server kit that provides OAuth 2.1/PKCE authentication, rate limiting, scope-gated tools, and two-phase confirmation for building secure MCP servers with custom tools, identity, and storage.24 npmMIT