Agent MCP Gateway

🚀 Agent MCP Gateway

Agent MCP Gatewayは、複数のMCPサーバーを集約し、エージェントとサブエージェントに対してポリシーベースのアクセス制御を提供するModel Context Protocol (MCP)ゲートウェイです。Claude CodeのMCPコンテキストウィンドウの浪費を解消し、すべてのツール定義を最初から読み込むのではなく、必要に応じてツールを発見できるようにします。

🚀 クイックスタート

1. ゲートウェイファイルの設定

uvx agent-mcp-gateway --init を実行した後（インストールを参照）、生成されたテンプレートファイルを編集します。

# 下流のMCPサーバーを定義する
nano ~/.config/agent-mcp-gateway/.mcp.json

# エージェントのアクセスポリシーを定義する
nano ~/.config/agent-mcp-gateway/.mcp-gateway-rules.json

詳細な例については、設定セクションを参照し、代替のファイル場所については、設定ファイルの探索を参照してください。

2. MCPクライアントにゲートウェイを追加する

Claude Code CLI:

claude mcp add agent-mcp-gateway uvx agent-mcp-gateway

手動設定:

{
  "mcpServers": {
    "agent-mcp-gateway": {
      "command": "uvx",
      "args": ["agent-mcp-gateway"],
      "env": {
        "GATEWAY_MCP_CONFIG": "~/.config/agent-mcp-gateway/.mcp.json",
        "GATEWAY_RULES": "~/.config/agent-mcp-gateway/.mcp-gateway-rules.json",
        "GATEWAY_DEFAULT_AGENT": "developer"
      }
    }
  }
}

注: デフォルトの設定場所を使用する場合、env 変数はオプションです。すべてのオプションについては、環境変数の参照を参照してください。

3. エージェントの設定

ゲートウェイのツール説明は自己文書化されていますが、適切なアクセス制御を行うには、エージェントが自分自身を識別する方法を設定する必要があります。あなたのユースケースに適したアプローチを選択してください。

アプローチ1: マルチエージェントモード（推奨）

異なる権限を持つ異なるエージェントの場合、各エージェントに自分の識別情報を渡すように設定します。

エージェントのシステムプロンプトにこれを追加します（例: CLAUDE.md, .claude/agents/agent-name.md）:

## MCPゲートウェイアクセス

**利用可能なツール（agent-mcp-gateway経由）:**

あなたは、agent-mcp-gatewayを介してMCPサーバーにアクセスできます。あなたがアクセスできる特定のサーバーとツールは、ゲートウェイのアクセス制御ルールによって決定されます。

**ツール発見プロセス:**

下流のMCPサーバーのツールを使用する必要がある場合:
1. 適切なアクセス制御のために、すべてのゲートウェイツール呼び出しで `agent_id: "YOUR_AGENT_NAME"` を使用します。
2. `list_servers` を呼び出して、あなたがアクセスできるサーバーを発見します。
3. 特定のサーバー名で `get_server_tools` を呼び出して、利用可能なツールを発見します。
4. `execute_tool` を使用して、適切なパラメーターでツールを呼び出します。
5. 必要なツールにアクセスできない場合は、すぐにユーザーに通知します。

**重要:** ゲートウェイツールの呼び出しには常に `agent_id: "YOUR_AGENT_NAME"` を含めてください。これにより、適切なアクセス制御と監査ログが確保されます。

YOUR_AGENT_NAME をエージェントの識別子（例: "researcher", "backend", "admin"）に置き換えてください。

例: 完全な設定例については、 と を参照してください。

アプローチ2: シングルエージェントモード

すべてのエージェントが同じ権限を持つようなシンプルな設定の場合、またはシステムプロンプトの設定ができないMCPクライアント（例: Claude Desktop）を使用する場合、いずれかの方法でデフォルトのエージェントを設定します。

オプションA: 環境変数

# MCPクライアントの設定で設定する
export GATEWAY_DEFAULT_AGENT=developer

注: 指定されたエージェント（例: "developer"）は、.mcp-gateway-rules.json ファイルに適切な権限で存在する必要があります。

オプションB: ルール内の "default" エージェント

{
  "agents": {
    "default": {
      "allow": {
        "servers": ["*"]
      }
    }
  },
  "defaults": {
    "deny_on_missing_agent": false
  }
}

注: すべてのサーバーを許可する ("servers": ["*"]) 場合、ツールの制限を指定せずにすべてのサーバーのすべてのツールにアクセスできます。

どちらのアプローチでも、エージェントはツール呼び出しで agent_id を省略できます - ゲートウェイは自動的に設定されたデフォルトのエージェントを使用します。

✨ 主な機能

• ✅ 必要に応じたツール発見 - 必要なときにのみツール定義を読み込む
• ✅ エージェントごとのアクセス制御 - 各エージェントがアクセスできるサーバー/ツールを設定する
• ✅ 簡単なエージェント統合 - 任意のエージェントにゲートウェイサポートを追加するためのシンプルなテンプレート (ガイドを参照)
• ✅ 拒否優先ポリシー - 明示的な拒否ルールが優先される
• ✅ ワイルドカードサポート - ツール名のパターンマッチング (get_*, *_user)
• ✅ セッション分離 - 同時リクエストが干渉しない
• ✅ 透過的なプロキシ - 下流のサーバーはゲートウェイを認識しない
• ✅ 監査ログ - すべての操作が監視のために記録される
• ✅ パフォーマンスメトリクス - エージェント/操作ごとのレイテンシとエラー率を追跡する
• ✅ ホット設定再読み込み - 再起動せずにルール/サーバーを更新する
• ✅ スレッドセーフな操作 - 再読み込み中の安全な同時アクセス

📦 インストール

# テンプレート設定ファイルを含む ~/.config/agent-mcp-gateway/ を作成する
uvx agent-mcp-gateway --init

これにより、カスタマイズする準備ができた2つのテンプレートファイルが生成されます。

• mcp.json - 下流のMCPサーバー（Brave, Postgresなど）
• mcp-gateway-rules.json - エージェントごとのアクセスポリシー（各エージェントがどのサーバー/ツールにアクセスできるか）

ローカル開発用: 開発セクションを参照してください。

💻 使用例

基本的な使用法

from fastmcp import Client

async def gateway_workflow():
    async with Client('agent-mcp-gateway') as client:
        # 1. 利用可能なサーバーを発見する
        servers = await client.call_tool('list_servers', {
            'agent_id': 'researcher'
        })
        # レスポンス: [{"name": "brave-search", "description": "Web search..."}]

        # 2. 特定のサーバーからツールを取得する
        tools = await client.call_tool('get_server_tools', {
            'agent_id': 'researcher',
            'server': 'brave-search'
        })
        # レスポンス: {"tools": [...], "server": "brave-search", ...}

        # 3. ツールを実行する
        result = await client.call_tool('execute_tool', {
            'agent_id': 'researcher',
            'server': 'brave-search',
            'tool': 'brave_web_search',
            'args': {'query': 'MCP protocol documentation'}
        })
        # レスポンス: {"content": [...search results...], "isError": false}

高度な使用法

# ゲートウェイのヘルスチェックと再読み込みステータスを確認する（GATEWAY_DEBUG=true が必要）
status = await client.call_tool('get_gateway_status', {
    "agent_id": "admin"
})

# 最後の再読み込みが成功したことを確認する
if status["reload_status"]["gateway_rules"]["last_error"]:
    print("Warning: Last rule reload failed!")

📚 ドキュメント

• 製品要件文書
• M0: 基礎仕様
• M0: 成功レポート
• M1: コア仕様
• M1: 成功レポート
• FastMCP実装ガイド
• Claude Codeサブエージェントの制限

🔧 技術詳細

コンポーネント図

┌─────────────────────────────────────────────────────────┐
│                    Agent / Client                       │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│              Agent MCP Gateway                          │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Gateway Tools (3 tools, ~2k tokens)             │  │
│  │  • list_servers                                   │  │
│  │  • get_server_tools                               │  │
│  │  • execute_tool                                   │  │
│  └───────────────────────────────────────────────────┘  │
│                      │                                  │
│  ┌─────────────────────────────────────────────────┐    │
│  │  AgentAccessControl Middleware                  │    │
│  │  • Extract agent_id                             │    │
│  │  • Validate permissions                         │    │
│  └─────────────────────────────────────────────────┘    │
│                      │                                  │
│  ┌─────────────────────────────────────────────────┐    │
│  │  PolicyEngine                                   │    │
│  │  • Deny-before-allow precedence                 │    │
│  │  • Wildcard matching                            │    │
│  └─────────────────────────────────────────────────┘    │
│                      │                                  │
│  ┌─────────────────────────────────────────────────┐    │
│  │  ProxyManager                                   │    │
│  │  • Session isolation                            │    │
│  │  • Connection pooling                           │    │
│  └─────────────────────────────────────────────────┘    │
│                      │                                  │
│  ┌─────────────────────────────────────────────────┐    │
│  │  AuditLogger & MetricsCollector                 │    │
│  └─────────────────────────────────────────────────┘    │
└──────────────────────┬──────────────────────────────────┘
                       │
         ┌─────────────┼─────────────┐
         ▼             ▼              ▼
   ┌─────────┐   ┌─────────┐   ┌─────────┐
   │ Server  │   │ Server  │   │ Server  │
   │   A     │   │   B     │   │   C     │
   │ (stdio) │   │ (stdio) │   │ (HTTP)  │
   └─────────┘   └─────────┘   └─────────┘

リクエストフロー

1. エージェントが agent_id を含むゲートウェイツールにリクエストを送信する
2. ミドルウェアがインターセプトする: agent_id を抽出して検証する
3. ツールが検証する: PolicyEngineでサーバー/ツールのアクセスを確認する
4. プロキシが転送する: ProxyManagerが下流のサーバーにルーティングする
5. セッションが分離される: 各リクエストに新しい接続が割り当てられる
6. 結果が返される: エージェントに透過的に転送される
7. 監査ログが記録される: 操作がメトリクスとともに記録される

パフォーマンス特性

• コンテキスト削減: 90%以上 (2kトークン対5,000 - 50,000+トークン)
• 追加レイテンシ: <100ms (P95)
• ゲートウェイオーバーヘッド: 操作ごとに<30ms
• セッション分離: リクエストごとに自動的に行われる
• 同時リクエスト: 完全にサポートされる

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細については、LICENSE ファイルを参照してください。