mcp-helmet
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同じコードで両方のモードに対応しています。
Related MCP server: mcp-server-toolkit
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つのパターンが繰り返し見られました:
すべてのサーバーが同じ20〜40行のセットアップを書き直している。 トランスポートの選択、コンテンツのラップ、エラーフォーマット、シグナル処理など。SDKはビルドブロックを提供しますが、これは「家」そのものを提供します。
ローカルで動作するサーバーがプロダクションで壊れる。 Dockerコンテナが1回のレスポンスで終了する、Kubernetesポッドがセッションを失う、ロードバランサーがプローブするためのヘルスチェックがない。最近の調査では、リモートMCPエンドポイントの52%が停止していました。
誰も認証の方法を理解できていない。 「ツール内で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 initCLIスキャフォルダー + Dockerテンプレート
v0.1.0の安定版は、アルファサイクルで30日以上の実運用実績が得られた後にリリースされます。v0.2は ROADMAP に記載されています:Redisバックエンドのセッションストア、構造化ログミドルウェア、FastMCPプラグイン経由のPython移植など。
公式SDKとの関係
mcp-helmet はフォークでも、代替品でも、置き換えでもありません。これは利便性を高めるレイヤーです。
懸念事項 | 公式SDK | mcp-helmet |
プロトコル実装 | はい | いいえ、SDKに委譲 |
トランスポートクラス | はい | いいえ、SDKトランスポートをラップ |
ツール/リソース/プロンプト登録 | はい | はい、より軽量なAPI |
OAuthサーバーフロー | はい (v2開発版) | いいえ、対象外 |
Bearer/APIキーミドルウェア | v2でExpressと結合 | トランスポート非依存、構成可能 |
ヘルスチェック | いいえ | はい、計画済み |
セッションの外部化 | いいえ | アップストリームのSEPまでの暫定措置 |
Docker/デプロイテンプレート | いいえ | はい、計画済み |
SDKはピア依存関係です。ご自身のバージョンをご用意ください。SDKが重複する機能を追加した場合、ツールキットのミドルウェアは単なる薄いパススルーになります。
要件
Node.js 20+
@modelcontextprotocol/sdk^1.29.0TypeScript 5.4+ (推奨、必須ではありません)
Zod 3.22+ または 3.25+ (
zod/v4サブパス経由でv4に対応)
コントリビューション
プルリクエストとIssueを歓迎します。セットアップ、テスト、PRの規約については CONTRIBUTING.md を参照してください。
セキュリティ
責任ある開示プロセスについては SECURITY.md を参照してください。
ライセンス
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