Mcpvanguard

McpVanguard

MCP エージェントとツールサーバーのためのセキュリティゲートウェイです。

McpVanguard は AI エージェントと MCP サーバーの間に配置され、ツールの通信をリアルタイムで正規化・検査し、機密性の高い呼び出しが基盤となるツールに到達する前に、多層ポリシーを適用します。stdio サーバーの前段でローカルに実行することも、SSE および Streamable HTTP を介したホスト型ゲートウェイとして実行することもできます。

製品プロファイル — monitor、balanced、strict — を使って、段階的に導入できます。まず監査のみの検出から始め、次にバランスの取れた適用へ移行し、その後、本番環境の機密性が高いシステムに対して厳格な強化を有効にします。

既存の MCP サーバーを書き換える必要はありません。

開発者に選ばれる理由

MCP ワークフローは強力ですが、ツールがファイル、シェル、ネットワークを扱う場合には、ガードレールが重要になります。

McpVanguard は実行時の適用境界を追加し、次のことを可能にします。

• 通常のツール通信を維持する
• 安全でない呼び出しを実行前にブロックする
• 監査ログでポリシーの判断を検査・デバッグする
• 既存の MCP サーバーを書き換えることなく段階的に導入する

提供する機能

McpVanguard は、MCP ワークフローに対して明示的なポリシー適用を求める開発者やプラットフォームチーム向けです。

• MCP ツールの呼び出しを実行前に検査する
• 安全でないファイルシステム、コマンド、ネットワークのパターンをブロックする
• 機密性の高いツールに対する認証、ロール、スコープの要件を適用する
• サーバーのメタデータが下流のモデルに届く前に検査する
• 繰り返し発生する不審な動作を継続的に追跡する
• ブロック、警告、許可された通信について監査・テレメトリ信号を出力する

簡単な検証シナリオ

同じ MCP サーバーに対して、生のパスと保護されたパスをそれぞれ使います。

• 安全なファイル読み取りは、どちらのパスでも許可される
• パストラバーサルの試みは、保護されたパスでブロックされる
• リスクのあるネットワークリクエストは、保護されたパスでブロックされる
• メタデータ汚染の試みは、モデルに公開される前にフィルタリングまたはブロックされる

これにより、ポリシーが有効であり、想定どおりに適用されていることをすばやく確認できます。

2.2.2 で認証情報を使わず、合成データによる確認を行うには、python -m core.demo_verify を実行します。 明示的なデモ専用の安全領域を使用して、同梱のメモリ内アップストリームに対する 無害な読み取りと、ブロックされる 2 件の呼び出しを確認します。インストール方法、 想定される出力、別途行う実際のワークフロー評価については、 セルフサービス評価をご覧ください。それ以前のリリースには、 この検証ツールは含まれていません。

ユースケース

• ローカルのデスクトップまたは開発者マシン上の MCP サーバーを書き換えずに保護する
• 共有 MCP サーバーの前段にホスト型ゲートウェイを追加する
• リスクのあるツールワークフローについて、生の動作と保護された動作を比較する
• リスクの高いファイル、シェル、ネットワークアクセス用ツールにポリシー適用を追加する

クイックスタート

パッケージをインストールします：

pip install mcp-vanguard

オプションのデプロイ用追加機能：

# Multi-instance L3 behavioral state
pip install "mcp-vanguard[redis]"

# RE2-backed deterministic regex matching where the wheel is available
pip install "mcp-vanguard[re2]"

# Hosted/full deployment extras
pip install "mcp-vanguard[full]"

ローカルの stdio MCP サーバーをラップします：

# Balanced profile (default OSS/developer behavior)
vanguard start --profile balanced --server "npx @modelcontextprotocol/server-filesystem ."

# Strict profile (production hardening)
vanguard start --profile strict --server "npx @modelcontextprotocol/server-filesystem ."

ホスト型ゲートウェイとして実行します：

export VANGUARD_API_KEY="replace-with-a-long-random-secret"
vanguard sse --profile balanced --server "npx @modelcontextprotocol/server-filesystem ."

パブリック環境、またはループバック以外を使用するホスト型デプロイでは、トランスポート認証として長くランダムな VANGUARD_API_KEY、または OAuth/JWKS 設定が構成されていない場合、strict プロファイルは起動を拒否します。balanced はデモや段階的なロールアウトに引き続き適していますが、認証なしで外部公開されると強い警告を出します。

ホスト型デプロイでは、ツール呼び出しのレート、リスクの高い判定、ブロックの繰り返し試行に対するセッション単位の予算を、オプトインで有効にすることもできます。これらは、ローカルの OSS 利用時のデフォルトを変えることなく、多層ポリシーの経路にサーキットブレーカーを設けます。

ホスト型テンプレートや共有ゲートウェイを運用する場合は、VANGUARD_ALLOWED_SERVER_COMMANDS を設定して、McpVanguard が起動できる上流 MCP サーバーの実行ファイルを制限してください。

Anthropic MCP トンネル経由で到達するプライベートネットワーク上の MCP サーバーには、トンネル -> McpVanguard -> プライベート MCP サーバーの配置を推奨します。トンネルはネットワークへの露出を抑えます。McpVanguard は実行境界を強制します。

McpVanguard は、2.2.x 系で文書化された MCP 2026-07-28 互換性ベースラインを提供します。このベースラインには、オプトインのステートレス・トランスポートプロファイル、追加の Mcp-Method / Mcp-Name 整合性チェック、明示的な _meta 検査範囲が含まれます。Tasks、MCP Apps、サブスクリプション、MRTR、または最終仕様への完全な準拠を主張するものではありません。docs/MCP_2026_07_28_RC_COMPATIBILITY.md をご覧ください。

Railway にデプロイ：

デプロイ手順の全体を確認するには、docs/DEPLOYMENT.md、docs/railway-deployment-guide.md、docs/ANTHROPIC_MCP_TUNNELS.md をご覧ください。

はじめに

ローカルワークスペースを初期化します：

# 1. Initialize safe zones and .env template
vanguard init

# 2. Optionally update Claude Desktop server entries
vanguard configure-claude

# 3. Launch the local security dashboard
vanguard ui --port 4040

# 4. Run compliance and readiness checks
vanguard audit-compliance

仕組み

McpVanguard は、L0 から L3 に L1.5 を加えた5つの中核検査レイヤーを使用し、その周囲に認証ポリシーと最終ポリシーコンポーザーを配置しています。すべてのツール呼び出しは、上流 MCP サーバーに到達する前に検査されます。

レイヤー	目的	備考
L0 - 事前チェック	正規化と注釈付け（URL デコード、NFKC、ゼロ幅文字の除去、サイズ／深度の制限）	常時有効
認証	OAuth スコープの適用と破壊的なツールのポリシー	ロールを考慮
L1 - ルール	シグネチャ、再帰的な引数検査、安全な境界を使用した決定論的なブロック	高速経路
L1.5 - 偽装	信頼シグナルの偽装とスコアラーの操作を検出	プロファイルに依存
L2 - セマンティック	オプションの意図スコアリング（エスカレーション／ブロックは可能ですが、決定論的なブロックの解除はできません）	非同期
L3 - 振る舞い	セッションおよびシーケンスを考慮した異常チェック	状態を保持
ポリシーコンポーザー	最終判定：ALLOW / WARN / REVIEW / SHADOW-BLOCK / BLOCK	説明可能

中核となる検査レイヤーは L0、L1、L1.5、L2、L3 の5つです。認証ポリシーと最終ポリシーコンポーザーは、この中核経路の周囲に配置されています。

リクエストがブロックされると、エージェントには標準の JSON-RPC エラーが返され、上流サーバーには呼び出しが届きません。監査ログには主な理由と、裏付けとなるすべての検出結果が記録されます。

セーフゾーンは決定論的なパス境界チェックであり、OS のサンドボックス化やコンテナ分離の代わりにはなりません。標準的な名前や一般的なカスタム名を持つパス形式の引数を再帰的に検査しますが、本番環境へのデプロイでは、MCP ツールがアクセスできる実際のスキーマやディレクトリに合わせて、rules/safe_zones.yaml も調整してください。docs/SAFE_ZONES.md をご覧ください。

運用担当者によるトリアージ向けに、JSON 監査ログには SIEM での利用に適した判定フィールドと、主なレイヤー、ルールファミリー、プロファイルの影響、上流呼び出しの状態、調整のヒントを含む構造化された policy_explanation データが記録されます。docs/BLOCK_DECISIONS.md をご覧ください。

デプロイモデル

McpVanguard は、MCP ワークフロー向けのセキュリティゲートウェイとして理解するのが最適です。

• ローカル優先モード：開発者のマシン上で stdio MCP サーバーをラップします
• ゲートウェイモード：ホスト型または共有型のデプロイ向けに、強化された SSE および Streamable HTTP エンドポイントを公開します

一般的な経路：

AI Agent -> McpVanguard -> MCP Server -> Tools / Files / External Systems

現在の機能

• リクエストレート、同時実行数、セッションバインディング、セッション数を制御する、強化された SSE および Streamable HTTP トランスポート経路
• initialize と tools/list に対するメタデータ汚染の検査
• ベアラートークン認証を使用するデプロイ向けの JWT、JWKS、発行者、オーディエンス、クレーム、スコープの検証
• サーバーの整合性と機能のドリフト検証
• サーバー間の分離と server_id による追跡可能性
• 署名済みマニフェスト、来歴、分離署名、Sigstore に基づく信頼性検証
• 適用範囲を測定するためのベンチマークおよび分類ツール
• エクスポート／署名後に mcp-receipt でオフライン検証可能なランタイム証拠を得るための、任意の receipt_v1 JSONL 出力

ベンチマーク

McpVanguard には、敵対的および良性の MCP トラフィックを収録したベンチマークコーパスがパッケージされています。デプロイ前にプロファイルを比較するために使用してください：

vanguard benchmark-run --profile monitor
vanguard benchmark-run --profile balanced
vanguard benchmark-run --profile strict
vanguard benchmark-profiles
vanguard benchmark-baselines

ベンチマーク結果はリリースやチューニングの判断材料であり、あらゆる状況での検出や誤検知ゼロを保証するものではありません。解釈のガイダンスと推奨されるリリースゲートについては、docs/BENCHMARKS.md を参照してください。

レイヤー化された設計の根拠となる公開研究ノートについては、Why MCP Security Needs Layered Runtime Enforcement を参照してください。

認証モード

McpVanguard はローカル優先で、必要に応じてホスト型ゲートウェイのより強固な制御をサポートします。

• stdio モード：ネットワーク認証は不要です
• SSE／Streamable HTTP モード：VANGUARD_API_KEY をサポートします
• ベアラー／JWT モード：検証済みの JWT／JWKS 検証、発行者／オーディエンス／クレーム／スコープのチェック、およびホスト型ゲートウェイ経路での認証対応ポリシーをサポートします
• 厳格なホスト型モード：トランスポート認証なしでのパブリックバインドを拒否し、ベアラークレームの不一致処理を block に設定し、許可リストが設定されている場合は Origin を必須とします

管理プレーン

ネイティブの vanguard_* 管理ツールは、デフォルトで無効になっています。有効にする場合は、明示的な管理プレーンモードも選択してください：

• disabled：ネイティブ管理ツールは公開されません
• same_session_dev：ローカル／開発環境専用です。読み取りツールと変更ツールは、管理対象の同一 MCP セッションを共有し、起動時に警告が表示されます
• operator_only：読み取り専用ツールは表示される場合がありますが、変更ツールを使用するには管理者ロール、または vanguard:admin／scope:admin スコープが必要です

本番環境では、呼び出し元が認証済みのオペレーターでない限り、通常の管理対象エージェントセッションで変更を伴う管理操作を行わないでください。管理操作は監査され、拒否された試行や変更を伴う試行はリスクとして可視化されます。

セマンティックバックエンドの選択肢

オプションのレイヤー 2 セマンティックスコアラーは、複数のバックエンドをサポートしています。最初に設定されたバックエンドが使用されます。

バックエンド	環境変数	備考
Universal Custom	VANGUARD_SEMANTIC_CUSTOM_KEY、関連するカスタム変数	Groq や DeepSeek などの高速推論プロバイダー
OpenAI	VANGUARD_OPENAI_API_KEY	デフォルトモデル：gpt-4o-mini
Ollama	VANGUARD_OLLAMA_URL	ローカルで実行でき、API キーは不要です

ローカル／オフライン環境での詳しいセットアップガイドについては、docs/LOCAL_SEMANTIC_MODE.md を参照してください。

整合性と信頼性

McpVanguard には、以下の機能が含まれています：

• 署名済みのアップストリームサーバーマニフェスト
• 機能のベースラインとドリフトチェック
• 来歴検証フック
• 分離されたアーティファクト署名の検証
• ID と発行者の制約を適用した Sigstore バンドルの検証

これは、包括的な SBOM プラットフォームではなく、サーバーの整合性、ベースライン検証、信頼性検証として説明する必要があります。

プロジェクトのステータス

• 2.2.x は、ランタイムの堅牢化と MCP 2026-07-28 互換性ベースラインを担う現在の系列です
• 階層型の適用パス（L0 -> L1 -> L1.5 -> L2 -> L3 -> Policy Composer）が実装され、ローカルおよび CI での検証によりカバーされています
• このリリース系列でサポートされるデプロイモードは、製品プロファイル（monitor / balanced / strict）です
• より広範な研究専用機能（GPU による証明、ハードウェアを起点とする来歴、ゼロ FP の主張）は、意図的にコア OSS リリースの対象外としています

リリース履歴については CHANGELOG.md を、デプロイの詳細については docs/DEPLOYMENT.md をご覧ください。

プライバシー

McpVanguard はローカルでの検査とゲートウェイによる適用に重点を置いています。現在のプライバシーおよびデータ取り扱いの詳細については、PRIVACY.md をご覧ください。

サポート

• 課題：github.com/provnai/McpVanguard/issues
• お問い合わせ：[email protected]
• セキュリティ：SECURITY.md をご覧ください

よくある質問

これは MCP サーバーを置き換えるものですか？
いいえ。McpVanguard は既存の MCP サーバーの手前に配置され、呼び出しがサーバーに到達する前にポリシーを適用します。

ツールやエージェントのコードを書き換える必要がありますか？
通常は必要ありません。ほとんどの場合、まず 1 つのワークフローを McpVanguard 経由でルーティングします。

ホスティング環境専用ですか？
いいえ。ローカル優先の stdio ラッピングと、ホスト型のゲートウェイモードに対応しています。

ライセンス

MIT License — 詳細については LICENSE をご覧ください。

Provnai が開発しました。