mcp-helmet

MCPサーバー向けのプロダクション用ミドルウェア。認証、セッション、ヘルスチェック、グレースフルシャットダウン、トランスポートの人間工学的な操作を提供します。Expressの helmet の精神を受け継いだ、構成可能なミドルウェアです。

mcp-helmet は、公式の @modelcontextprotocol/sdk をラップし、SDKには含まれていない機能（自動トランスポート検出、コンテンツのラップ、ヘルスチェック、グレースフルシャットダウン、セッション管理、認証ミドルウェア）を提供します。これらすべてが1つのパッケージにまとまっており、構成可能です。不要な機能は削除できます。Hello Worldからプロダクション環境への移行を、数日ではなく数分で実現します。

npm install mcp-helmet @modelcontextprotocol/sdk zod

ピア依存関係: @modelcontextprotocol/sdk ^1.29.0, zod ^3.22.0 または ^3.25 (v4)。zod-to-json-schema は Zod v3 ユーザー向けのオプションのピア依存関係です。

クイックスタート

最も速い方法はスキャフォルダーを使用することです：

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

これにより、healthCheck()、gracefulShutdown()、オプションの認証、マルチステージの Dockerfile、型チェック済みの tsconfig を備えた動作可能なMCPサーバーが手に入ります。フラグを使用して一部の機能をスキップしたり（--no-docker、--no-health など）、後からカスタマイズしたりできます。

または、手動で構築します：

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

以上です。トランスポートの配線やコンテンツ配列の構築、シグナルハンドラーの記述は不要です。実行します：

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

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

同じコードで両方のモードに対応しています。

6行で実装する認証

Bearerトークンの検証を行い、検証済みのプリンシパルを任意のツールハンドラー内で利用できます：

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

単一引数のツールハンドラーのシグネチャはそのままです。getAuthContext() は AsyncLocalStorage から読み取るため、非同期チェーンのどの深さからでも動作します。

なぜこのツールが存在するのか

私たちは30のプロダクションMCPサーバーと、公式SDK全体で320のGitHub Issueを調査しました。その結果、3つのパターンが繰り返し見られました：

1. すべてのサーバーが同じ20〜40行のセットアップを書き直している。 トランスポートの選択、コンテンツのラップ、エラーフォーマット、シグナル処理など。SDKはビルドブロックを提供しますが、これは「家」そのものを提供します。

2. ローカルで動作するサーバーがプロダクションで壊れる。 Dockerコンテナが1回のレスポンスで終了する、Kubernetesポッドがセッションを失う、ロードバランサーがプローブするためのヘルスチェックがない。最近の調査では、リモートMCPエンドポイントの52%が停止していました。

3. 誰も認証の方法を理解できていない。 「ツール内でBearerトークンにアクセスするにはどうすればよいか？」は、両方のSDKリポジトリで最も多く寄せられる質問です。

mcp-helmet は、SDKを置き換えることなく拡張する構成可能なミドルウェアによって、これらの問題を解決します。

ステータス

v0.1.0-alpha — 機能完了。 現在提供されている機能：

• ✅ 自動コンテンツラップ（文字列、オブジェクト、Content[]）を備えた createServer()

• ✅ MCP_TRANSPORT 環境変数による自動トランスポート検出

• ✅ Zod v3 + v4 互換性シム

• ✅ 構成可能なミドルウェアシステム (server.use(mw))

• ✅ healthCheck() ミドルウェア

• ✅ gracefulShutdown() ミドルウェア

• ✅ AsyncLocalStorage ベースの getAuthContext() を備えた bearerAuth() および apiKeyAuth() ミドルウェア

• ✅ rateLimiter() ミドルウェア（スライディングウィンドウ、IPまたはキーベース、標準の429ヘッダー）

• ✅ npx mcp-helmet init CLIスキャフォルダー + Dockerテンプレート

v0.1.0の安定版は、アルファサイクルで30日以上の実運用実績が得られた後にリリースされます。v0.2は ROADMAP に記載されています：Redisバックエンドのセッションストア、構造化ログミドルウェア、FastMCPプラグイン経由のPython移植など。

公式SDKとの関係

mcp-helmet はフォークでも、代替品でも、置き換えでもありません。これは利便性を高めるレイヤーです。

SDKはピア依存関係です。ご自身のバージョンをご用意ください。SDKが重複する機能を追加した場合、ツールキットのミドルウェアは単なる薄いパススルーになります。

要件

• Node.js 20+

• @modelcontextprotocol/sdk ^1.29.0

• TypeScript 5.4+ (推奨、必須ではありません)

• Zod 3.22+ または 3.25+ (zod/v4 サブパス経由でv4に対応)

コントリビューション

プルリクエストとIssueを歓迎します。セットアップ、テスト、PRの規約については CONTRIBUTING.md を参照してください。

セキュリティ

責任ある開示プロセスについては SECURITY.md を参照してください。

ライセンス

MIT