mcp-helmet

Production middleware for MCP servers. Auth, sessions, health checks, graceful shutdown, transport ergonomics. Composable middleware borrowed in spirit from Express's helmet.

mcp-helmet wraps the official @modelcontextprotocol/sdk with the things it doesn't ship: auto transport detection, content wrapping, health checks, graceful shutdown, session management, and auth middleware. One package. Composable. Drop what you don't need. Go from hello world to production in minutes, not days.

npm install mcp-helmet @modelcontextprotocol/sdk zod

Alpha note. Until 0.1.0 stable cuts, the latest dist-tag points at the most recent alpha (currently 0.1.0-alpha.7). npm install mcp-helmet resolves there; pin a specific version if you prefer to opt out of alpha churn. Once the ROADMAP gates clear, latest moves to the stable release.

Peer dependencies: @modelcontextprotocol/sdk ^1.29.0, zod ^3.22.0 or ^3.25 (v4). zod-to-json-schema is an optional peer for Zod v3 users.

Quickstart

The fastest way is the scaffolder:

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

You get a working MCP server with healthCheck(), gracefulShutdown(), optional auth, a multistage Dockerfile, a typechecked tsconfig, a passing test, and a CI workflow. Drop flags to skip pieces (--no-docker, --no-health, --no-rate-limit, --no-tests, --no-ci) or customise after the fact.

Want richer worked examples with auth, rate limiting, and audit logging? See examples/.

Or wire it manually:

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

That's it. No transport wiring, no content array construction, no signal handlers. Run it:

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

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

Same code, both modes.

Auth in 6 lines

Bearer token verification, with the verified principal available inside any tool handler:

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

The single-argument tool handler signature stays the same — getAuthContext() reads from AsyncLocalStorage, so it works from any depth in the async chain.

Why this exists

We audited 30 production MCP servers and 320 GitHub issues across the official SDKs. Three patterns kept showing up:

1. Every server rewrites the same 20-40 lines of setup. Transport selection, content wrapping, error formatting, signal handling. The SDK gives you the building blocks; this gives you the house.

2. Servers that work locally break in production. Docker containers exit after one response, Kubernetes pods lose sessions, no health check for load balancers to probe. 52% of remote MCP endpoints in a recent survey were dead.

3. Nobody can figure out auth. "How do I access the bearer token inside my tool?" is the most asked question across both SDK repos.

mcp-helmet solves these with composable middleware that extends the SDK without replacing it.

Status

v0.1.0-alpha — feature complete. Currently shipped:

• ✅ createServer() with auto content wrapping (string, object, Content[])

• ✅ Auto transport detection via MCP_TRANSPORT env var

• ✅ Zod v3 + v4 compatibility shim

• ✅ Composable middleware system (server.use(mw))

• ✅ healthCheck() middleware

• ✅ gracefulShutdown() middleware

• ✅ bearerAuth() and apiKeyAuth() middleware with AsyncLocalStorage-based getAuthContext()

• ✅ rateLimiter() middleware (sliding window, IP- or key-based, standard 429 headers)

• ✅ requestLog() middleware (one JSON line per request, captures auth principal automatically)

• ✅ npx mcp-helmet init CLI scaffolder + Docker template

• ✅ examples/ directory with three runnable scenarios

v0.1.0 stable will follow once the alpha cycle has 30+ days of real-world usage and a small set of confirmed users. The full plan, including v0.2 scope, gates, forcing events, and a kill switch, lives in ROADMAP.md.

Performance

Per-request overhead is below the measurement noise floor. Numbers from a single Node 20 run on Apple M1; expect 5-15% variance across runs.

full stack / bare = 0.98x mean latency, ie middleware cost is below what this benchmark can measure at the per-request scale. p99 stays sub-millisecond. Run npm run bench to reproduce on your hardware; the script exits non-zero if a future change pushes the ratio above 5x.

See benchmarks/README.md for tunables and methodology.

Migrate from the raw SDK

If you already have an MCP server using @modelcontextprotocol/sdk directly, mcp-helmet drops in without rewriting your tools. Three concrete swaps:

// Before
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({ name: "x", version: "1.0.0" });
server.tool("greet", { name: z.string() }, async ({ name }) => ({
  content: [{ type: "text", text: `Hello, ${name}!` }],
}));
const transport = new StdioServerTransport();
await server.connect(transport);

// After
import { createServer } from "mcp-helmet";

const server = createServer({ name: "x", version: "1.0.0" });
server.tool("greet", { name: z.string() }, async ({ name }) => `Hello, ${name}!`);
await server.start();

The handler returns a string and gets auto wrapped into TextContent. The transport is selected from MCP_TRANSPORT (defaults to stdio). The underlying McpServer is still available as server.raw if you need it.

Adding middleware afterwards is one line per concern:

server.use(healthCheck());
server.use(requestLog());
server.use(rateLimiter({ max: 100, windowMs: 60_000 }));
server.use(bearerAuth({ verify: myVerifier }));
server.use(gracefulShutdown());

Troubleshooting

getAuthContext() returns undefined inside my tool handler. The auth middleware that populates the context (bearerAuth or apiKeyAuth) must be installed via server.use(...) before server.start(). The toolkit reads getAuthContext() from AsyncLocalStorage scoped to each HTTP request. If you call it from a stdio server (no HTTP request lifecycle), it always returns undefined.

Graceful shutdown does not fire. gracefulShutdown() only listens for SIGTERM / SIGINT in the toolkit's HTTP path. In stdio mode the parent process owns the lifecycle (Claude Desktop, Inspector, your spawn parent), so the toolkit does not need to register signal handlers.

tools/list is empty. Call server.tool(...) before server.start(). Tool registration is captured at start time; tools registered afterwards are not advertised.

The rate limiter never triggers. rateLimiter() only runs in HTTP mode because stdio has no per-request HTTP lifecycle for the middleware to hook. Including it in a stdio server is a harmless no-op.

Zod v3 vs v4 imports look weird. The toolkit detects which Zod major you have and adapts at runtime. If you are on Zod 3.22+ on the v3 line, just import { z } from "zod". If you are on Zod 4 and want the new APIs, use import * as z from "zod/v4". The toolkit accepts schemas from either.

StreamableHTTPClientTransport returns 401. You have an auth middleware in the chain. Pass the right Authorization header in requestInit.headers when constructing the client transport. See examples/02-http-bearer-rate-limit.ts.

Testing a tool that calls getAuthContext(). InMemoryTransport bypasses the HTTP request lifecycle, which is the layer that normally wraps each request with runWithAuthContext. So tools that read the auth principal via getAuthContext() return undefined under in-memory tests by default. Inject auth manually by wrapping the callTool invocation:

import { runWithAuthContext } from "mcp-helmet";

const result = await runWithAuthContext(
  { user: "test-user", scopes: ["read", "write"] },
  () => client.callTool({ name: "whoami", arguments: {} }),
);

This is the pattern used in mcp-helmet-fs-example to test scope-based authorization without going through HTTP.

How it relates to the official SDK

mcp-helmet is not a fork, an alternative, or a replacement. It's a convenience layer.

The SDK is a peer dependency. You bring your own version. If the SDK adds features that overlap, mcp-helmet middleware becomes a thin pass-through.

Requirements

• Node.js 20+

• @modelcontextprotocol/sdk ^1.29.0

• TypeScript 5.4+ (recommended, not required)

• Zod 3.22+ or 3.25+ (v4 via zod/v4 subpath)

Contributing

PRs and issues welcome. See CONTRIBUTING.md for setup, test, and PR conventions.

Security

See SECURITY.md for the responsible disclosure path.

License

MIT