Agent MCP Gateway

Agent MCP Gateway

Model Context Protocol（MCP） ゲートウェイです。複数の MCP サーバーを集約し、エージェントとサブエージェントにポリシーベースのアクセス制御を提供します。すべてのツール定義をあらかじめ読み込む代わりに、必要に応じてツールを検出できるようにすることで、Claude Code の MCP コンテキストウィンドウの浪費を解消します。

ステータス

• ✅ M0：基盤 - 設定、ポリシーエンジン、監査ログ、list_servers ツール
• ✅ M1：コア - プロキシインフラストラクチャ、get_server_tools、execute_tool、ミドルウェア、メトリクス、ホットリロード、OAuth サポート
• 🚧 M2：本番環境 - HTTP トランスポート、ヘルスチェック（予定）
• 🚧 M3：開発者体験 - シングルエージェントモード、設定検証 CLI、Docker（予定）

現在のバージョン： M1-Core 完了（OAuth 対応）

目次

• 概要
• インストール
• クイックスタート
• コマンドラインオプション
• 設定ファイルの検出
• 設定
• 使用方法
• ゲートウェイツール
• セキュリティに関する考慮事項
• トラブルシューティング
• テスト
• 開発
• アーキテクチャ
• 今後の機能
• ドキュメント
• 貢献
• ライセンス
• サポート
• 謝辞

概要

問題

開発環境（Claude Code、Cursor、VS Code）で複数の MCP サーバーを設定すると、起動時にすべてのサーバーのツール定義が、すべてのエージェントとサブエージェントのコンテキストウィンドウに読み込まれます。

• 起動時に 5,000～50,000 個以上のトークンを消費
• 読み込まれたツールの 80～95％は、個々のエージェントで使用されない
• 実際の作業に必要なコンテキストが、未使用のツール定義に費やされる

解決策

Agent MCP Gateway は、エージェントごとに設定可能なルールに基づいて複数の下流 MCP サーバーにプロキシする、単一の MCP サーバーとして機能します。

• 3 つのゲートウェイツールを起動時に読み込み（約 2k トークン）
• エージェントは必要に応じて特定のツールを検出し、リクエストできます
• コンテキストを 90％以上削減
• エージェント／サブエージェントごとのポリシーベースのアクセス制御

仕組み

ゲートウェイはエージェントと下流 MCP サーバーの間に位置し、軽量な 3 つのツールのみを公開します。特定の機能が必要になると、エージェントはゲートウェイを通じて利用可能なサーバーとツールを検出します。ゲートウェイはポリシールールに基づいて表示対象を絞り込み、エージェントにはアクセス権のあるサーバーとツールのみを表示します。これにより、各エージェントのコンテキストウィンドウを関連するツールだけに限定しつつ、ゲートウェイが認可済みリクエストを下流サーバーにプロキシします。

例を含む詳細な図を見る →（下流サーバー、ツール、ゲートウェイルールの例を含む）

主な機能

• ✅ 必要に応じたツール検出 - 必要なときにのみツール定義を読み込みます
• ✅ エージェントごとのアクセス制御 - 各エージェントがアクセスできるサーバー／ツールを設定できます
• ✅ エージェントとの簡単な連携 - シンプルなテンプレートで、任意のエージェントにゲートウェイサポートを追加できます（ガイドを参照）
• ✅ 拒否優先ポリシー - 明示的な拒否ルールが優先されます
• ✅ ワイルドカード対応 - ツール名のパターンマッチング（get_*、*_user）
• ✅ セッション分離 - 同時リクエストが互いに干渉しません
• ✅ 透過的なプロキシ - 下流サーバーはゲートウェイの存在を認識しません
• ✅ 監査ログ - 監視のため、すべての操作を記録します
• ✅ パフォーマンスメトリクス - エージェント／操作ごとのレイテンシとエラー率を追跡します
• ✅ 設定のホットリロード - 再起動せずにルール／サーバーを更新できます
• ✅ スレッドセーフな操作 - リロード中も安全に並行アクセスできます
• ✅ 診断ツール - get_gateway_status によるヘルスモニタリング（デバッグモードのみ）

インストール

# Creates ~/.config/agent-mcp-gateway/ with template configuration files
uvx agent-mcp-gateway --init

カスタマイズできるテンプレートファイルが2つ生成されます。

• mcp.json - 接続先のMCPサーバー（Brave、Postgresなど）
• mcp-gateway-rules.json - エージェントごとのアクセス許可ポリシー（どのエージェントがどのサーバーやツールを使用できるか）

ローカル開発の場合： 開発セクションを参照してください。

クイックスタート

1. ゲートウェイファイルを設定する

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

# Define your downstream MCP servers
nano ~/.config/agent-mcp-gateway/.mcp.json

# Define agent access policies
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 Gateway Access

**Available Tools (via agent-mcp-gateway):**

You have access to MCP servers through the agent-mcp-gateway. The specific servers and tools available to you are determined by the gateway's access control rules.

**Tool Discovery Process:**

When you need to use tools from downstream MCP servers:
1. Use `agent_id: "YOUR_AGENT_NAME"` in ALL gateway tool calls for proper access control
2. Call `list_servers` to discover which servers you have access to
3. Call `get_server_tools` with the specific server name to discover available tools
4. Use `execute_tool` to invoke tools with appropriate parameters
5. If you cannot access a tool you need, immediately notify the user

**Important:** Always include `agent_id: "YOUR_AGENT_NAME"` in your gateway tool calls. This ensures proper access control and audit logging.

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

例： 設定例の全体については、.claude/agents/researcher.md と .claude/agents/mcp-developer.md を参照してください。

方法2：シングルエージェントモード

すべてのエージェントに同じ権限を付与するシンプルな構成や、システムプロンプトを設定できないMCPクライアント（例：Claude Desktop）を使用する場合は、次のいずれかの方法でデフォルトのエージェントを設定します。

オプションA：環境変数

# Set in your MCP client configuration
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 を省略できます。ゲートウェイは設定済みのデフォルトエージェントを自動的に使用します。

コマンドラインオプション

# Show version
agent-mcp-gateway --version

# Initialize config directory (first-time setup)
agent-mcp-gateway --init

# Enable debug mode (exposes get_gateway_status diagnostic tool)
agent-mcp-gateway --debug

# Show help
agent-mcp-gateway --help

設定ファイルの検出

ゲートウェイは次の順序で設定ファイルを検索します。

MCP サーバー設定（.mcp.json）

1. GATEWAY_MCP_CONFIG 環境変数（設定されている場合）
2. 現在のディレクトリにある .mcp.json
3. ~/.config/agent-mcp-gateway/.mcp.json（ホームディレクトリ）
4. ./config/.mcp.json（フォールバック）

ゲートウェイルール（.mcp-gateway-rules.json）

1. GATEWAY_RULES 環境変数（設定されている場合）
2. 現在のディレクトリにある .mcp-gateway-rules.json
3. ~/.config/agent-mcp-gateway/.mcp-gateway-rules.json（ホームディレクトリ）
4. ./config/.mcp-gateway-rules.json（フォールバック）

ヒント： 初回実行時にホームディレクトリの設定ファイルを作成するには、agent-mcp-gateway --init を使用してください。

設定

ゲートウェイには次の2つの設定ファイルが必要です。

1. MCP サーバーの設定

ファイル： mcp.json（複数の場所を検索します）

ゲートウェイがプロキシ接続する下流の MCP サーバーを定義します。Claude Code やその他のコーディングエージェントと互換性のある、標準の MCP 設定形式を使用します。

{
  "mcpServers": {
    "brave-search": {
      "description": "Web search via Brave Search API",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    },
    "postgres": {
      "description": "PostgreSQL database access and query execution",
      "command": "uvx",
      "args": ["mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "remote-server": {
      "description": "Custom remote API integration",
      "url": "https://example.com/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

サーバーの説明（推奨）： 各サーバーに description フィールドを追加すると、各サーバーが提供するものや、使用するタイミングを AI エージェントが理解しやすくなります。説明は常に list_servers によって返されるため、エージェントはどのサーバーにツールを問い合わせるべきかを、情報に基づいて判断できます。説明は任意ですが、追加することでエージェントによるツールの検出と意思決定が大幅に改善されます。

サポートされているトランスポート：

• stdio - npx/uvx を介したローカルサーバー（command + args で指定）
• http - リモート HTTP サーバー（url で指定）

環境変数：

• 環境変数の置換には ${VAR_NAME} 構文を使用します
• 実行前に変数を設定します：export BRAVE_API_KEY=your-key

重要 - GUI アプリケーション（Claude Desktop など）： .mcp.json で ${VAR_NAME} 構文を使用する場合、macOS の GUI アプリケーションは分離された環境で実行されるため、シェルの環境変数にアクセスできない点に注意してください。Claude Desktop などのアプリでは、MCP クライアント設定のゲートウェイの env オブジェクトに API キーを追加してください。

{
  "mcpServers": {
    "agent-mcp-gateway": {
      "command": "uvx",
      "args": ["agent-mcp-gateway"],
      "env": {
        "BRAVE_API_KEY": "your-actual-key-here",
        "DATABASE_URL": "postgresql://...",
        "GATEWAY_DEFAULT_AGENT": "claude-desktop"
      }
    }
  }
}

（${VAR_NAME} 構文を使わずに .mcp.json に値を直接ハードコードする場合、この操作は必要ありません。）

2. ゲートウェイルールの設定

ファイル： mcp-gateway-rules.json（複数の場所で検索されます）

拒否が許可より優先されるルールに基づいて、エージェントごとのアクセス ポリシーを定義します。

{
  "agents": {
    "researcher": {
      "allow": {
        "servers": ["brave-search", "context7"],
        "tools": {
          "brave-search": ["brave_web_search"]
        }
      }
    },
    "backend": {
      "allow": {
        "servers": ["postgres", "laravel-boost"],
        "tools": {
          "postgres": ["query", "list_tables", "list_schemas"],
          "laravel-boost": ["get_*", "list_*", "read_*", "database_*", "search_*"]
        }
      },
      "deny": {
        "tools": {
          "postgres": ["drop_*", "delete_*"],
          "laravel-boost": ["database_query", "tinker"]
        }
      }
    },
    "admin": {
      "allow": {
        "servers": ["*"],
        "tools": {
          "brave-search": ["brave_web_search"]
        }
      },
      "deny": {
        "servers": ["notion"],
        "tools": {
          "playwright": ["browser_type"]
        }
      }
    },
    "claude-desktop": {
      "allow": {
        "servers": ["context7", "brave-search", "notion", "playwright"]
      },
      "deny": {
        "tools": {
          "playwright": ["browser_type", "browser_close_all", "launch_*"]
        }
      }
    },
    "default": {
      "deny": {
        "servers": ["*"]
      }
    }
  },
  "defaults": {
    "deny_on_missing_agent": false
  }
}

エージェントの例の説明：

researcher - 暗黙的な許可と明示的な許可の例です：

• brave-search：brave_web_search ツールのみ（明示的な許可によってアクセスを制限します）
• context7：すべてのツール（暗黙的な許可 — サーバーは許可されており、ツールルールは指定されていません）

backend - ワイルドカード許可と、拒否が許可より優先されるルールの例です：

• postgres：query、list_tables、list_schemas のみ（明示的な許可）；拒否ルールはセーフティネットとして機能します
• laravel-boost：ワイルドカード許可（get_*、list_*、read_*、database_*、search_*）によって広範なアクセスを許可します。ただし、database_query は database_* ワイルドカードに一致するにもかかわらず明示的に拒否されます（拒否が優先されます）。また、安全対策として tinker もブロックされます

admin - サーバーのワイルドカードと、混在するアクセスパターンの例です：

• notion：拒否（サーバーレベルの拒否は、ワイルドカードによるサーバーの許可より優先されます）
• brave-search：brave_web_search のみ（1 つのサーバーに対する明示的な制限）
• playwright：browser_type を除くすべてのツール（明示的な拒否を伴う暗黙的な許可）
• その他すべてのサーバー：すべてのツール（暗黙的な許可 — ツールルールは指定されていません）

claude-desktop - 複数種類の拒否を伴う暗黙的な許可の例です：

• context7、brave-search、notion：すべてのツール（暗黙的な許可）
• playwright：browser_type、browser_close_all、および launch_* に一致するツールを除くすべてのツール（明示的な拒否とワイルドカードによる拒否を伴う暗黙的な許可）

default - 最小権限の原則：

• agent_id が指定されず、deny_on_missing_agent が false の場合にフォールバックとして使用されます
• デフォルトですべてのサーバーを拒否します。別のデフォルトエージェントを指定するには、GATEWAY_DEFAULT_AGENT 環境変数を使用します

ポリシーの優先順位：

1. 明示的な拒否ルール（最優先）
2. ワイルドカードによる拒否ルール
3. 明示的な許可ルール
4. ワイルドカードによる許可ルール
5. 暗黙的な許可（サーバーが許可されているものの、ツールルールが指定されていない場合）
6. デフォルトポリシー（拒否）

暗黙的な許可の動作：

• エージェントがサーバーへのアクセス権を持ち、allow.tools.{server} エントリーがない場合、そのサーバーのすべてのツールが暗黙的に許可されます
• allow.tools.{server} エントリーがある場合、アクセスは指定されたツールのみに制限されます
• deny.tools.{server} エントリーは特定のツールを除外します（ステップ 1〜2 で評価されます）
• ルールはサーバーごとに適用され、他のサーバーには影響しません

設定の柔軟性：

• 現在 .mcp.json にないサーバーもルールで参照できます
• 未定義のサーバー参照はエラーではなく警告として扱われます
• 一時的に削除されたサーバーのルールを保持できます
• ホットリロードにより、再起動せずに変更がすぐに適用されます

ワイルドカードパターン：

• * - すべてに一致します
• get_* - "get_" で始まるツールに一致します
• *_user - "_user" で終わるツールに一致します

エージェントの命名：

• 階層型の名前を使用します：team.role（例：backend.database、frontend.ui）
• 英数字、ハイフン、アンダースコア、ドットを使用できます
• エージェントを設定するには、エージェントが自身の ID を渡すようにします：エージェントの設定を参照してください

設定の検証

ゲートウェイは起動時とホットリロード時に設定を検証します。出力例：

✓ Configuration loaded from .mcp.json
⚠ Warning: Agent 'researcher' references undefined server 'unknown-server'
ℹ These rules will be ignored until the server is added

検証の動作：

• 構造上のエラー（無効な JSON、必須フィールドの不足）→ 起動／リロードに失敗します
• 未定義のサーバー参照 → 警告をログに記録し、有効なルールを使って処理を続行します
• ポリシーの競合 → 拒否が許可より優先されるルールによって自動的に解決されます

3. 下流サーバーの OAuth サポート

OAuth で保護された下流サーバー（Notion、GitHub）は、サーバーが HTTP 401 を返すと自動検出によってサポートされます。ゲートウェイは FastMCP の OAuth サポートを使用して認証フローを透過的に処理します。初回認証時にブラウザーが一度開き、その後の使用に備えてトークンがキャッシュされます。詳しい設定方法とトラブルシューティングについては、OAuth ユーザーガイドを参照してください。

OAuth の制限事項：

ゲートウェイは、**Dynamic Client Registration（RFC 7591）**を実装している OAuth サーバーをサポートします。

• ✅ サポート対象： 自動検出による OAuth（例：Notion MCP）
• ❌ サポート対象外： 事前登録済みアプリを使う OAuth（例：GitHub OAuth フロー）
• 💡 GitHub MCP の場合： 代わりに Personal Access Token を使用してください

PAT を使用する GitHub MCP の例：

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    }
  }
}

OAuth の詳しい設定方法とトラブルシューティングについては、OAuth ユーザーガイドを参照してください。

4. 環境変数のリファレンス

変数	説明	デフォルト	例
GATEWAY_MCP_CONFIG	MCP サーバー設定ファイルへのパス	.mcp.json、フォールバック：./config/.mcp.json	export GATEWAY_MCP_CONFIG=./custom.json
GATEWAY_RULES	ゲートウェイルール設定ファイルへのパス	.mcp-gateway-rules.json、フォールバック：./config/.mcp-gateway-rules.json	export GATEWAY_RULES=~/.claude/rules.json
GATEWAY_DEFAULT_AGENT	agent_id が指定されていない場合のデフォルトのエージェント ID（任意）	なし	export GATEWAY_DEFAULT_AGENT=developer
GATEWAY_DEBUG	デバッグモードを有効にして get_gateway_status ツールを公開する	false	export GATEWAY_DEBUG=true
GATEWAY_AUDIT_LOG	監査ログファイルへのパス	~/.cache/agent-mcp-gateway/logs/audit.jsonl	export GATEWAY_AUDIT_LOG=./audit.jsonl
GATEWAY_TRANSPORT	トランスポートプロトコル（stdio または http）	stdio	export GATEWAY_TRANSPORT=stdio
GATEWAY_INIT_STRATEGY	初期化戦略（eager または lazy）	eager	export GATEWAY_INIT_STRATEGY=eager

GUI アプリケーションに関する注意： macOS の GUI アプリケーション（Claude Desktop など）は、シェル環境変数にアクセスできない隔離された環境で実行されます。.mcp.json で ${VAR_NAME} 構文を使用する場合は、MCP クライアント設定のゲートウェイの env オブジェクトに必要な API キーを追加してください。

使用方法

MCP クライアントの起動時に、ゲートウェイは自動的に実行されます。MCP クライアント設定への追加方法については、クイックスタートを参照してください。

カスタム設定パスは、MCP クライアント設定で環境変数を使って指定できます。

{
  "mcpServers": {
    "agent-mcp-gateway": {
      "command": "uvx",
      "args": ["agent-mcp-gateway"],
      "env": {
        "GATEWAY_MCP_CONFIG": "/path/to/custom-mcp.json",
        "GATEWAY_RULES": "/path/to/custom-rules.json"
      }
    }
  }
}

使用可能なオプションについては、環境変数のリファレンスを参照してください。

起動時の出力

Loading MCP server configuration from: .mcp.json
Loading gateway rules from: .mcp-gateway-rules.json
Audit log will be written to: ~/.cache/agent-mcp-gateway/logs/audit.jsonl

Initializing proxy connections to downstream servers...
  - 2 proxy client(s) initialized
    * brave-search: ready
    * postgres: ready
  - Metrics collector initialized
  - Access control middleware registered

Agent MCP Gateway initialized successfully
  - 2 MCP server(s) configured
  - 3 agent(s) configured
  - Default policy: deny unknown agents
  - 3 gateway tools available: list_servers, get_server_tools, execute_tool
  (4 tools if GATEWAY_DEBUG=true: includes get_gateway_status)

Gateway is ready. Running with stdio transport...

ゲートウェイツール

ゲートウェイはエージェントに対して、ちょうど 3 つのツールを公開します。すべてのツールは、アクセス制御用の省略可能な agent_id パラメーターを受け付けます。agent_id が指定されていない場合、ゲートウェイはフォールバックチェーンを使ってエージェント ID を特定します（エージェント ID のモードを参照）。

エージェント開発者向け： アクセス制御を有効にして、これらのゲートウェイツールをエージェントが適切に使用できるよう設定する方法については、エージェントを設定するを参照してください。

1. list_servers

ポリシールールに基づいて、呼び出し元のエージェントが利用できる MCP サーバーを一覧表示します。

パラメーター：

• agent_id（文字列、省略可能）- リクエストを行うエージェントの識別子（エージェント ID のモードを参照）
• include_metadata（ブール値、省略可能）- トランスポート、コマンド、URL などの技術的な詳細を含めます（デフォルト：false）

戻り値：

[
  {
    "name": "brave-search",
    "description": "Web search via Brave Search API"
  },
  {
    "name": "postgres",
    "description": "PostgreSQL database access and query execution"
  }
]

include_metadata=true の場合：

[
  {
    "name": "brave-search",
    "description": "Web search via Brave Search API",
    "transport": "stdio",
    "command": "npx"
  },
  {
    "name": "postgres",
    "description": "PostgreSQL database access and query execution",
    "transport": "stdio",
    "command": "uvx"
  }
]

注意： エージェントが各サーバーの提供機能を理解できるよう、サーバーの説明は（.mcp.json で設定されている場合）常に含まれます。include_metadata フラグで制御されるのは、技術的な詳細（トランスポート、コマンド、URL）を含めるかどうかのみです。

例：

# Basic usage - returns names and descriptions
result = await client.call_tool("list_servers", {
    "agent_id": "researcher"
})

# With technical metadata
result = await client.call_tool("list_servers", {
    "agent_id": "researcher",
    "include_metadata": True
})

2. get_server_tools

特定の MCP サーバーからツール定義を取得し、エージェントの権限に基づいてフィルタリングします。

パラメーター:

• agent_id（string、任意）- エージェントの識別子（エージェントの識別モードを参照）
• server（string、必須）- 下流の MCP サーバーの名前
• names（string、任意）- ツール名をカンマ区切りで指定したリスト（例："tool1,tool2,tool3"）または単一のツール名
• pattern（string、任意）- ツール名のワイルドカードパターン（例："get_*"）
• max_schema_tokens（integer、任意）- スキーマのトークン予算の上限

戻り値:

{
  "tools": [
    {
      "name": "brave_web_search",
      "description": "Search the web using Brave Search",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {"type": "string"}
        },
        "required": ["query"]
      }
    }
  ],
  "server": "brave-search",
  "total_available": 5,
  "returned": 1,
  "tokens_used": 150
}

例:

# Get all allowed tools
tools = await client.call_tool("get_server_tools", {
    "agent_id": "researcher",
    "server": "brave-search"
})

# Get specific tools by name (comma-separated)
tools = await client.call_tool("get_server_tools", {
    "agent_id": "researcher",
    "server": "brave-search",
    "names": "brave_web_search,brave_local_search"
})

# Get specific tools by pattern
tools = await client.call_tool("get_server_tools", {
    "agent_id": "backend",
    "server": "postgres",
    "pattern": "get_*"
})

# Limit token usage
tools = await client.call_tool("get_server_tools", {
    "agent_id": "researcher",
    "server": "brave-search",
    "max_schema_tokens": 1000
})

3. execute_tool

結果を透過的に転送しながら、下流の MCP サーバーでツールを実行します。

パラメーター:

• agent_id（string、任意）- エージェントの識別子（エージェントの識別モードを参照）
• server（string、必須）- 下流の MCP サーバーの名前
• tool（string、必須）- 実行するツールの名前
• args（object、必須）- ツールに渡す引数
• timeout_ms（integer、任意）- タイムアウト時間（ミリ秒）

戻り値:

{
  "content": [
    {
      "type": "text",
      "text": "Search results: ..."
    }
  ],
  "isError": false
}

例:

# Execute a tool
result = await client.call_tool("execute_tool", {
    "agent_id": "researcher",
    "server": "brave-search",
    "tool": "brave_web_search",
    "args": {
        "query": "FastMCP documentation"
    }
})

# With timeout
result = await client.call_tool("execute_tool", {
    "agent_id": "backend",
    "server": "postgres",
    "tool": "query",
    "args": {
        "sql": "SELECT * FROM users LIMIT 10"
    },
    "timeout_ms": 5000
})

4. get_gateway_status（デバッグモードのみ）

ゲートウェイの包括的な健全性情報と診断情報を返します。

重要: このツールは、デバッグモードが有効な場合（環境変数 GATEWAY_DEBUG=true または CLI フラグ --debug によって）のみ利用できます。詳しくはセキュリティ上の考慮事項を参照してください。

パラメーター:

• agent_id（string、任意）- エージェントの識別子（エージェントの識別モードを参照）

戻り値:

{
  "reload_status": {
    "mcp_config": {
      "last_attempt": "2025-10-30T10:30:00Z",
      "last_success": "2025-10-30T10:30:00Z",
      "last_error": null,
      "attempt_count": 1,
      "success_count": 1
    },
    "gateway_rules": {
      "last_attempt": "2025-10-30T10:35:00Z",
      "last_success": "2025-10-30T10:35:00Z",
      "last_error": null,
      "attempt_count": 2,
      "success_count": 2,
      "last_warnings": []
    }
  },
  "policy_state": {
    "total_agents": 3,
    "agent_ids": ["researcher", "backend", "admin"],
    "defaults": {"deny_on_missing_agent": true}
  },
  "available_servers": ["brave-search", "postgres"],
  "config_paths": {
    "mcp_config": "/path/to/.mcp.json",
    "gateway_rules": "/path/to/.mcp-gateway-rules.json"
  },
  "message": "Gateway is operational. Check reload_status for hot reload health."
}

例:

# Check gateway health and reload status (requires GATEWAY_DEBUG=true)
status = await client.call_tool("get_gateway_status", {
    "agent_id": "admin"
})

# Verify last reload was successful
if status["reload_status"]["gateway_rules"]["last_error"]:
    print("Warning: Last rule reload failed!")

エラー処理

すべてのツールは、明確なメッセージを含む構造化エラーを返します。

{
  "error": {
    "code": "DENIED_BY_POLICY",
    "message": "Agent 'frontend' denied access to tool 'drop_table'",
    "rule": "agents.frontend.deny.tools.postgres[0]"
  }
}

エラーコード:

• DENIED_BY_POLICY - エージェントに権限がありません
• SERVER_UNAVAILABLE - 下流のサーバーに接続できません
• TOOL_NOT_FOUND - 要求されたツールが存在しません
• TIMEOUT - 操作が制限時間を超過しました
• INVALID_AGENT_ID - エージェント識別子が指定されていないか、不明です
• FALLBACK_AGENT_NOT_IN_RULES - 設定されたフォールバックエージェントがゲートウェイルール内に見つかりません
• NO_FALLBACK_CONFIGURED - agent_id が指定されておらず、フォールバックエージェントも設定されていません

ワークフローの完全な例

一般的なゲートウェイのワークフローを示す、最小限の動作例です。

from fastmcp import Client

async def gateway_workflow():
    async with Client('agent-mcp-gateway') as client:
        # 1. Discover available servers
        servers = await client.call_tool('list_servers', {
            'agent_id': 'researcher'
        })
        # Response: [{"name": "brave-search", "description": "Web search..."}]

        # 2. Get tools from specific server
        tools = await client.call_tool('get_server_tools', {
            'agent_id': 'researcher',
            'server': 'brave-search'
        })
        # Response: {"tools": [...], "server": "brave-search", ...}

        # 3. Execute a tool
        result = await client.call_tool('execute_tool', {
            'agent_id': 'researcher',
            'server': 'brave-search',
            'tool': 'brave_web_search',
            'args': {'query': 'MCP protocol documentation'}
        })
        # Response: {"content": [...search results...], "isError": false}

このワークフローでは、必要なときにのみツール定義を読み込む、オンデマンドのツール検出を示します。事前に読み込む必要はありません。

エージェントの識別モード

ゲートウェイは、エージェントの識別を扱うために2つのデプロイモードをサポートしています。

マルチエージェントモード（推奨）

異なるエージェントに異なる権限が必要な場合（本番環境、マルチエージェントシステム）に使用します。

{
  "agents": {
    "researcher": {"allow": {"servers": ["brave-search"]}},
    "backend": {"allow": {"servers": ["postgres"]}}
  },
  "defaults": {
    "deny_on_missing_agent": true  // Require explicit agent_id
  }
}

各エージェントが自分の識別情報を渡すように設定してください（エージェントの設定を参照）。

シングルエージェントモード

すべてのエージェントに同じ権限を付与する場合（開発、個人利用、シングルエージェントのデプロイ）に使用します。

# Set default agent via environment variable
export GATEWAY_DEFAULT_AGENT=developer

または、ルール内で「default」エージェントを定義します。

{
  "agents": {
    "default": {
      "allow": {"servers": ["brave-search", "postgres"]}
    }
  },
  "defaults": {
    "deny_on_missing_agent": false
  }
}

エージェントはツール呼び出しで agent_id を省略できます。その場合、ゲートウェイは設定されたデフォルトを自動的に使用します。

技術的な詳細：エージェント識別情報の解決

agent_id が指定されていない場合、ゲートウェイは次のフォールバックチェーンを使用します。

1. GATEWAY_DEFAULT_AGENT 環境変数（最優先）
2. .mcp-gateway-rules.json 内の「default」という名前のエージェント
3. どちらも設定されていない場合はエラー

deny_on_missing_agent 設定でこの動作を制御します。

• true：明示的な agent_id を必須とします（フォールバックチェーンを無効化）
• false：agent_id が省略された場合、フォールバックチェーンを使用します

セキュリティに関する注意: フォールバックの仕組みは最小権限の原則に従います。暗黙的に「すべてを許可」するアクセス権を与えることはなく、明示的に設定されたエージェントの権限のみを使用します。

## セキュリティに関する考慮事項

ルールファイルの保存場所： コンテキスト最適化のみを目的とする場合は、プロジェクト内に .mcp-gateway-rules.json を保存してください。本番環境でのアクセス制御を目的とする場合は、エージェントによる権限の読み取りや変更を防ぐため、プロジェクトディレクトリの外（例：~/.claude/mcp-gateway-rules.json）に保存してください。

デバッグモード： get_gateway_status ツールはゲートウェイの内部情報を公開し、GATEWAY_DEBUG=true の場合にのみ使用できます。本番環境では無効にしてください。

包括的なセキュリティガイダンスについて： ルールファイルのセキュリティ、デバッグモードに関する考慮事項、エージェントのなりすましリスク、本番環境でのベストプラクティスの詳細については、セキュリティガイドを参照してください。

トラブルシューティング

ゲートウェイが起動しない

症状： 起動時にエラーが発生する、またはゲートウェイの初期化に失敗する

解決方法：

• 設定ファイルが存在することを確認する： .mcp.json と .mcp-gateway-rules.json が想定される場所にあることを確認してください
• JSON の構文を検証する： python -m json.tool < .mcp.json を実行し、構文エラーがないか確認してください
• Python のバージョンを確認する： Python 3.12 以降がインストールされていることを確認してください（python --version）
• 依存関係を確認する： uv sync を実行し、すべてのパッケージがインストールされていることを確認してください

下流サーバーに接続できない

症状： ツールの呼び出し時に SERVER_UNAVAILABLE エラーが発生する

解決方法：

• サーバー設定を確認する： .mcp.json でサーバーが正しく定義されていることを確認してください
• stdio サーバーをテストする： コマンドを実行できることを確認してください（npx --version、uvx --version）
• 環境変数を確認する： API キーと認証情報が設定されていることを確認してください
• HTTP サーバーをテストする： ブラウザーでサーバーの URL に直接アクセスしてみてください
• 起動ログを確認する： ゲートウェイの出力でサーバー初期化エラーを探してください

権限拒否エラー

症状： エージェントがツールを使用しようとした際に DENIED_BY_POLICY が発生する

解決方法：

• agent_id を確認する： エージェントが正しい ID を渡していることを確認してください（監査ログを確認してください）
• エージェントのルールを確認する： .mcp-gateway-rules.json にエージェントが存在することを確認してください
• ポリシーの優先順位を確認する： 拒否ルールは許可ルールより優先されることに注意してください
• ワイルドカードでテストする： 一時的に広範なアクセス権を付与するため、"tools": {"server-name": ["*"]} を試してください
• デバッグモードを有効にする： GATEWAY_DEBUG=true を設定して get_gateway_status を呼び出し、ポリシーの状態を調べてください

OAuth 認証の問題

症状： ブラウザーが開かない、または OAuth フローに失敗する

詳しいトラブルシューティングについては、OAuth ユーザーガイドを参照してください。

簡単な対処方法：

• トークンキャッシュを消去する： rm -rf ~/.fastmcp/oauth-mcp-client-cache/
• ブラウザーをテストする： python -m webbrowser https://example.com
• サーバー URL を確認する： .mcp.json で正しい OAuth サーバー URL が設定されていることを確認してください

ホットリロードが機能しない

症状： 設定ファイルを変更しても反映されない

解決方法：

• ファイルの監視を確認する： 設定ファイルが想定される場所にあることを確認してください
• ログを確認する： ゲートウェイの出力でリロードエラーを探してください
• 手動でリロードする： SIGHUP シグナルを送信するか、ゲートウェイを再起動してください
• デバッグモード： get_gateway_status を使用して、最後にリロードした時刻を確認してください

その他のサポートについて： セキュリティガイド、OAuth ユーザーガイドを参照するか、GitHub の issue を作成してください。

テスト

MCP Inspector を使用したテスト

MCP Inspector は、MCP サーバーをテストするためのインタラクティブなツールです。

# Basic usage
npx @modelcontextprotocol/inspector uvx agent-mcp-gateway

# With custom config paths
GATEWAY_MCP_CONFIG=~/.config/agent-mcp-gateway/.mcp.json \
GATEWAY_RULES=~/.config/agent-mcp-gateway/.mcp-gateway-rules.json \
GATEWAY_DEFAULT_AGENT=researcher \
npx @modelcontextprotocol/inspector uvx agent-mcp-gateway

# With debug mode
GATEWAY_DEBUG=true npx @modelcontextprotocol/inspector uvx agent-mcp-gateway

Inspector の機能：

• スキーマ付きのすべてのゲートウェイツールを表示する
• 任意の入力を使ってツールをテストする
• リクエストとレスポンスのメッセージを調べる
• ログと通知を監視する

Inspector でゲートウェイツールをテストする

1. list_servers をテストする：

{
  "agent_id": "researcher"
}

期待される結果：「researcher」エージェントがアクセスできるサーバーの一覧。

2. get_server_tools をテストする：

{
  "agent_id": "researcher",
  "server": "brave-search"
}

期待される結果：brave-search サーバーのツール定義。

3. execute_tool をテストする：

{
  "agent_id": "researcher",
  "server": "brave-search",
  "tool": "brave_web_search",
  "args": {
    "query": "test query"
  }
}

期待される結果：Brave の検索結果（サーバーが設定済みで、稼働している場合）。

トラブルシューティング：

• Logs ペインでエラーを確認してください
• ルールファイルに agent_id が存在することを確認してください
• 下流サーバーが設定されていることを確認してください
• Message ペインでポリシーによる拒否を確認してください

開発

ローカルインストール

クローンして開発モードでインストールします。

# Clone repository
git clone https://github.com/roddutra/agent-mcp-gateway.git
cd agent-mcp-gateway

# Install dependencies
uv sync

# Create local config files from examples
cp config/.mcp.json.example .mcp.json
cp config/.mcp-gateway-rules.json.example .mcp-gateway-rules.json

# Run locally
uv run python main.py --help

ローカルゲートウェイを MCP クライアントに追加する

# Claude Code CLI
claude mcp add agent-mcp-gateway \
  uv run --directory /path/to/agent-mcp-gateway python main.py

# Or manual configuration
{
  "mcpServers": {
    "agent-mcp-gateway": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/agent-mcp-gateway", "python", "main.py"],
      "env": {
        "GATEWAY_DEFAULT_AGENT": "developer"
      }
    }
  }
}

注記： --directory フラグを指定すると、uv run は実行前にプロジェクトディレクトリへ移動します。これにより、pyproject.toml とゲートウェイの設定ファイルが確実に見つかります。

プロジェクト構成

agent-mcp-gateway/
├── src/                          # Core gateway implementation
├── tests/                        # Test suite
├── config/                       # Configuration examples
├── docs/                         # Documentation and specifications
├── main.py                       # Entry point
└── pyproject.toml                # Python dependencies

開発環境での実行

# Run locally
uv run python main.py

# With debug mode
uv run python main.py --debug

テスト

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-report=term

# Run specific test file
uv run pytest tests/test_gateway.py -v

# Run tests in watch mode
uv run pytest-watch

# Generate HTML coverage report
uv run pytest --cov=src --cov-report=html
open htmlcov/index.html

MCP Inspector を使ったテスト：

# Basic usage (uses local config files)
npx @modelcontextprotocol/inspector uv run python main.py

# With debug mode
npx @modelcontextprotocol/inspector uv run python main.py --debug

# With custom config paths
GATEWAY_MCP_CONFIG=.mcp.json \
GATEWAY_RULES=.mcp-gateway-rules.json \
GATEWAY_DEFAULT_AGENT=researcher \
npx @modelcontextprotocol/inspector uv run python main.py

FastMCP Client を使った手動テスト：

uv run python -c "
import asyncio
from fastmcp import Client

async def test():
    async with Client('main.py') as client:
        result = await client.call_tool('list_servers', {'agent_id': 'researcher'})
        print(result)

asyncio.run(test())
"

新機能の追加

1. 仕様を更新する：関連するマイルストーンファイルに記載します
2. まずテストを書く：tests/ にテストファイルを作成します
3. 機能を実装する：src/ にコードを追加します
4. テストを実行する：uv run pytest
5. カバレッジを確認する：uv run pytest --cov=src
6. ドキュメントを更新する：README と関連ファイルに記載します
7. コミットする：コミットメッセージの形式に従います

コードスタイル

• M0/M1 のコードにある既存のパターンに従います
• 全体を通して型ヒントを使用します
• すべての公開関数に docstring を記述します
• 関数の役割を絞り、テスト可能な状態に保ちます
• すべての新機能にテストを追加します

アーキテクチャ

コンポーネント図

┌─────────────────────────────────────────────────────────┐
│                    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
• セッション分離：リクエストごとに自動で実行
• 同時リクエスト：完全にサポート

今後の機能

M2：本番環境（予定）

🚧 ステータス： まだ実装されていません

機能：

• ゲートウェイサーバー向け HTTP トランスポート
• ヘルスチェックエンドポイント
• エラーハンドリングの強化
• メトリクスエクスポート API
• コネクションプーリングの最適化
• レート制限

利用可能になった場合：

# Run with HTTP transport
export GATEWAY_TRANSPORT=http
export GATEWAY_PORT=8080
uv run python main.py

# Health check endpoint
curl http://localhost:8080/health

# Metrics endpoint
curl http://localhost:8080/metrics

M3：開発者エクスペリエンス（予定）

🚧 ステータス： まだ実装されていません

機能：

• シングルエージェントモード（agent_id の要件を回避）
• 設定検証用 CLI ツール
• サンプル付き Docker コンテナ
• 対話型セットアップウィザード
• VS Code 拡張機能

利用可能になった場合：

# Single-agent mode (no agent_id required)
export GATEWAY_DEFAULT_AGENT=developer
uv run python main.py

# Validate configs
uv run python -m src.cli validate

# Run with Docker
docker run -v ./config:/config agent-mcp-gateway

ドキュメント

• 製品要件定義書
• M0：基盤仕様
• M0：成功レポート
• M1：コア仕様
• M1：成功レポート
• FastMCP 実装ガイド
• Claude Code サブエージェントの MCP に関する制限事項

コントリビューション

コントリビューションを歓迎します。以下をお願いします。

1. PRD と関連するマイルストーン仕様を読む
2. 既存のコードスタイルとパターンに従う
3. すべての新機能にテストを書く
4. すべてのテストがパスすることを確認する：uv run pytest
5. 必要に応じてドキュメントを更新する
6. 内容が明確な説明を添えてプルリクエストを送信する

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。

サポート

問題や質問については、以下をご利用ください。

• GitHub Issues：Issue を作成
• ドキュメント：docs/
• MCP 仕様：https://modelcontextprotocol.io

謝辞

以下を使用して構築されています。

• FastMCP - MCP サーバーのフレームワーク
• Model Context Protocol - プロトコル仕様