mcp-policy-gateway

ポリシー優先のMCPサーバー リファレンス実装。エージェントに有用なツールを提供しつつ、モデルが認可を決定したり、テナント境界を越えたり、直接的なPIIを漏洩させたり、高影響の変更を単独で実行したりすることを防ぐ方法を示します。

これはポートフォリオ/リファレンス実装です。すべてのレコードは合成データであり、本番ソフトウェアではなく、銀行、決済処理業者、顧客システムとの統合を主張するものではありません。

なぜこれが存在するのか

一般的なMCPデモは、生のAPIをモデルに公開し、ツール呼び出しの成功をセキュリティモデルとして扱います。このプロジェクトは逆の立場を取ります：

• ポリシーは決定的です。 モデルは自分自身を認可できません。

• テナント境界はサーバー側で強制されます。 ツール引数でテナントを切り替えることはできません。

• ツール出力は最小化されます。 アカウントサマリーは意図的に所有者名とメールを除外します。

• 高影響のアクションは承認ゲートで停止します。 凍結リクエストは状態変更を生成しません。

• すべての決定は監査可能です。 許可、拒否、承認必須の結果は構造化された監査イベントを生成します。

• 変更リクエストには理由と冪等性キーが必要です。

Related MCP server: scopeguard-mcp

アーキテクチャ

MCP client / agent
       │ tool call
       ▼
FastMCP stdio adapter
       │ verified principal (demo fixture here)
       ▼
GatewayService ──► PolicyEngine ──► allow / deny / require approval
       │                 │
       ▼                 ▼
synthetic domain data   structured audit event

本番デプロイでは、プリンシパルはモデルコンテキスト外の検証済みアイデンティティ/セッションから導出されます。tenant_id、ロール、スコープをツール引数やモデル出力から受け入れてはいけません。

ツール

クイックスタート

Python 3.11+ が必要です。

python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
.venv/bin/ruff check .

MCP stdioサーバーとして実行：

.venv/bin/mcp-policy-gateway

アダプターはローカル探索用に意図的に固定されたデモプリンシパルを使用します。実際のアイデンティティ伝播は、ここで偽装するのではなく、本番統合の関心事として意図的に文書化されています。

実証された悪用防止策

テストはゲートウェイが以下を証明します：

1. tenant_red のエージェントが tenant_blue のデータを読み取ろうとするのを拒否します。

2. 必要なスコープなしのツール呼び出しを拒否します。

3. サマリーツールを通じて所有者名やメールを返しません。

4. アカウント状態を変更する代わりに require_approval を返します。

5. 理由または冪等性キーを省略した状態変更リクエストを拒否します。

脅威モデルと非目標

THREAT_MODEL.md を参照してください。設計は意図的に狭い範囲です：MCPツールの周囲のポリシー境界を示すものであり、完全なアイデンティティ基盤、永続的な監査ストレージ、シークレット管理、または決済/台帳システムではありません。

面接ウォークスルー

プロジェクトを簡潔に説明する方法：

モデルが安全でスコープされたデータを推論できるが、アクセスを決定したり高影響のアクションを実行したりできないようにMCP境界を設計しました。認可は決定的であり、テナント分離はサーバー側で強制され、ツールサーフェスはPIIを最小化し、機密性の高い変更は監査可能な人間の承認ゲートで終了します。

開発

.venv/bin/pytest
.venv/bin/ruff check .

CIはプッシュとプルリクエストの両方で両方のチェックを実行します。

ライセンス

MIT。 LICENSE を参照してください。