Agent MCP Gateway

🚀 Agent MCP Gateway

Agent MCP Gateway 是一個 模型上下文協議 (MCP) 網關，它聚合了多個 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）
• ✅ 會話隔離 - 併發請求不會相互干擾
• ✅ 透明代理 - 下游服務器不知道網關的存在
• ✅ 審計日誌記錄 - 記錄所有操作以進行監控
• ✅ 性能指標 - 跟蹤每個代理/操作的延遲和錯誤率
• ✅ 熱配置重新加載 - 更新規則/服務器無需重啟
• ✅ 線程安全操作 - 重新加載期間安全的併發訪問
• ✅ 診斷工具 - 通過 get_gateway_status 進行健康監控（僅調試模式）

📦 安裝指南

# 創建 ~/.config/agent-mcp-gateway/ 幷包含模板配置文件
uvx agent-mcp-gateway --init

這將生成兩個準備好自定義的模板文件：

• 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("警告: 上次規則重新加載失敗!")

📚 詳細文檔

命令行選項

# 顯示版本
agent-mcp-gateway --version

# 初始化配置目錄（首次設置）
agent-mcp-gateway --init

# 啟用調試模式（暴露 get_gateway_status 診斷工具）
agent-mcp-gateway --debug

# 顯示幫助
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 創建主目錄配置。

配置

網關需要兩個配置文件：

1. MCP 服務器配置

文件：mcp.json（在多個位置搜索） 定義網關將代理到的下游 MCP 服務器。使用與 Claude Code 和其他編碼代理兼容的標準 MCP 配置格式：

{
  "mcpServers": {
    "brave-search": {
      "description": "通過 Brave Search API 進行網絡搜索",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    },
    "postgres": {
      "description": "PostgreSQL 數據庫訪問和查詢執行",
      "command": "uvx",
      "args": ["mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "remote-server": {
      "description": "自定義遠程 API 集成",
      "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 應用程序在隔離環境中運行，無法訪問你的 shell 環境變量。對於 Claude Desktop 和類似應用程序，將 API 密鑰添加到 MCP 客戶端配置中網關的 env 對象中：

{
  "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"
      }
    }
  }
}

（如果你直接在 .mcp.json 中硬編碼值而不使用 ${VAR_NAME} 語法，則不需要這樣做。）

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（對一個服務器的顯式限制）
  • 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）
• 允許字母數字字符、連字符、下劃線和點
• 配置你的代理 以傳遞其身份：請參閱配置你的代理

配置驗證

網關在啟動和熱重新加載期間驗證配置。示例輸出：

✓ 從 .mcp.json 加載配置
⚠ 警告: 代理 'researcher' 引用了未定義的服務器 'unknown-server'
ℹ 在添加服務器之前，這些規則將被忽略

驗證行為：

• 結構錯誤（無效的 JSON，缺少必需的字段）→ 啟動/重新加載失敗
• 未定義的服務器引用 → 記錄警告，繼續使用有效規則
• 政策衝突 → 先拒絕後允許的優先級自動解決

3. 下游服務器的 OAuth 支持

通過自動檢測，當服務器返回 HTTP 401 時，自動支持受 OAuth 保護的下游服務器（Notion，GitHub）。網關使用 FastMCP 的 OAuth 支持透明地處理身份驗證流程 - 瀏覽器首次打開進行初始身份驗證，然後令牌被緩存以供將來使用。有關詳細設置和故障排除，請參閱 OAuth 用戶指南。 OAuth 限制： 網關支持實現 動態客戶端註冊 (RFC 7591) 的 OAuth 服務器。

• ✅ 支持：具有自動檢測的 OAuth（例如，Notion MCP）
• ❌ 不支持：具有預註冊應用程序的 OAuth（例如，GitHub OAuth 流程）
• 💡 對於 GitHub MCP：使用個人訪問令牌代替 使用 PAT 的 GitHub MCP 示例：

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

有關詳細的 OAuth 設置和故障排除，請參閱 OAuth 用戶指南。

4. 環境變量參考

屬性	詳情
GATEWAY_MCP_CONFIG	MCP 服務器配置文件的路徑
GATEWAY_RULES	網關規則配置文件的路徑
GATEWAY_DEFAULT_AGENT	當未提供 agent_id 時的默認代理身份（可選）
GATEWAY_DEBUG	啟用調試模式以暴露 get_gateway_status 工具
GATEWAY_AUDIT_LOG	審計日誌文件的路徑
GATEWAY_TRANSPORT	傳輸協議（stdio 或 http）
GATEWAY_INIT_STRATEGY	初始化策略（eager 或 lazy）

注意：macOS GUI 應用程序（Claude Desktop 等）在隔離環境中運行，無法訪問 shell 環境變量。如果你在 .mcp.json 中使用 ${VAR_NAME} 語法，請將所需的 API 密鑰添加到 MCP 客戶端配置中網關的 env 對象中。

使用

網關在你的 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"
      }
    }
  }
}

所有可用選項請參閱環境變量參考。

啟動輸出

從 .mcp.json 加載 MCP 服務器配置
從 .mcp-gateway-rules.json 加載網關規則
審計日誌將寫入: ~/.cache/agent-mcp-gateway/logs/audit.jsonl

初始化與下游服務器的代理連接...
  - 初始化 2 個代理客戶端
    * brave-search: 就緒
    * postgres: 就緒
  - 初始化指標收集器
  - 註冊訪問控制中間件

Agent MCP 網關成功初始化
  - 配置了 2 個 MCP 服務器
  - 配置了 3 個代理
  - 默認策略: 拒絕未知代理
  - 3 個可用的網關工具: list_servers, get_server_tools, execute_tool
  (如果 GATEWAY_DEBUG=true，則為 4 個工具: 包括 get_gateway_status)

網關已就緒。使用 stdio 傳輸運行...

網關工具

網關向代理暴露了 3 個工具。所有工具都接受一個可選的 agent_id 參數以進行訪問控制。當未提供 agent_id 時，網關使用後備鏈來確定代理身份（請參閱代理身份模式）。 對於代理開發人員：要配置你的代理以正確使用這些網關工具並進行訪問控制，請參閱配置你的代理。

1. list_servers

根據策略規則列出調用代理可以訪問的 MCP 服務器。 參數：

• agent_id（字符串，可選） - 發出請求的代理的標識符（請參閱代理身份模式）
• include_metadata（布爾值，可選） - 包括技術細節，如傳輸、命令和 URL（默認：false） 返回：

[
  {
    "name": "brave-search",
    "description": "通過 Brave Search API 進行網絡搜索"
  },
  {
    "name": "postgres",
    "description": "PostgreSQL 數據庫訪問和查詢執行"
  }
]

當 include_metadata=true 時：

[
  {
    "name": "brave-search",
    "description": "通過 Brave Search API 進行網絡搜索",
    "transport": "stdio",
    "command": "npx"
  },
  {
    "name": "postgres",
    "description": "PostgreSQL 數據庫訪問和查詢執行",
    "transport": "stdio",
    "command": "uvx"
  }
]

注意：服務器描述總是包含在內（當在 .mcp.json 中配置時），以幫助代理瞭解每個服務器提供的內容。include_metadata 標誌僅控制是否包含技術細節（傳輸、命令、URL）。 示例：

# 基本用法 - 返回名稱和描述
result = await client.call_tool("list_servers", {
    "agent_id": "researcher"
})

# 包含技術元數據
result = await client.call_tool("list_servers", {
    "agent_id": "researcher",
    "include_metadata": True
})

2. get_server_tools

從特定的 MCP 服務器檢索工具定義，根據代理權限進行過濾。 參數：

• agent_id（字符串，可選） - 代理的標識符（請參閱代理身份模式）
• server（字符串，必需） - 下游 MCP 服務器的名稱
• names（字符串，可選） - 逗號分隔的工具名稱列表（例如，"tool1,tool2,tool3"）或單個工具名稱
• pattern（字符串，可選） - 工具名稱的通配符模式（例如，"get_*"）
• max_schema_tokens（整數，可選） - 模式的令牌預算限制 返回：

{
  "tools": [
    {
      "name": "brave_web_search",
      "description": "使用 Brave Search 搜索網絡",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {"type": "string"}
        },
        "required": ["query"]
      }
    }
  ],
  "server": "brave-search",
  "total_available": 5,
  "returned": 1,
  "tokens_used": 150
}

示例：

# 獲取所有允許的工具
tools = await client.call_tool("get_server_tools", {
    "agent_id": "researcher",
    "server": "brave-search"
})

# 按名稱獲取特定工具（逗號分隔）
tools = await client.call_tool("get_server_tools", {
    "agent_id": "researcher",
    "server": "brave-search",
    "names": "brave_web_search,brave_local_search"
})

# 按模式獲取特定工具
tools = await client.call_tool("get_server_tools", {
    "agent_id": "backend",
    "server": "postgres",
    "pattern": "get_*"
})

# 限制令牌使用
tools = await client.call_tool("get_server_tools", {
    "agent_id": "researcher",
    "server": "brave-search",
    "max_schema_tokens": 1000
})

3. execute_tool

在下游 MCP 服務器上執行工具，並透明地轉發結果。 參數：

• agent_id（字符串，可選） - 代理的標識符（請參閱代理身份模式）
• server（字符串，必需） - 下游 MCP 服務器的名稱
• tool（字符串，必需） - 要執行的工具的名稱
• args（對象，必需） - 要傳遞給工具的參數
• timeout_ms（整數，可選） - 超時時間（毫秒） 返回：

{
  "content": [
    {
      "type": "text",
      "text": "搜索結果: ..."
    }
  ],
  "isError": false
}

示例：

# 執行工具
result = await client.call_tool("execute_tool", {
    "agent_id": "researcher",
    "server": "brave-search",
    "tool": "brave_web_search",
    "args": {
        "query": "FastMCP 文檔"
    }
})

# 帶超時
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 環境變量或 --debug CLI 標誌）。有關詳細信息，請參閱安全考慮。 參數：

• agent_id（字符串，可選） - 代理的標識符（請參閱代理身份模式） 返回：

{
  "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": "網關正在運行。檢查 reload_status 以獲取熱重新加載健康信息。"
}

示例：

# 檢查網關健康和重新加載狀態（需要 GATEWAY_DEBUG=true）
status = await client.call_tool("get_gateway_status", {
    "agent_id": "admin"
})

# 驗證上次重新加載是否成功
if status["reload_status"]["gateway_rules"]["last_error"]:
    print("警告: 上次規則重新加載失敗!")

錯誤處理

所有工具都返回帶有清晰消息的結構化錯誤：

{
  "error": {
    "code": "DENIED_BY_POLICY",
    "message": "代理 'frontend' 被拒絕訪問工具 '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. 發現可用的服務器
        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}

此工作流演示了按需工具發現 - 僅在需要時加載定義，而不是提前加載。

代理身份模式

網關支持兩種處理代理身份的部署模式：

多代理模式（推薦）

當不同的代理需要不同的權限時使用（生產環境，多代理系統）：

{
  "agents": {
    "researcher": {"allow": {"servers": ["brave-search"]}},
    "backend": {"allow": {"servers": ["postgres"]}}
  },
  "defaults": {
    "deny_on_missing_agent": true  // 需要顯式的 agent_id
  }
}

配置每個代理以傳遞其身份（請參閱配置你的代理）。

單代理模式

當所有代理應具有相同的權限時使用（開發環境，個人使用，單代理部署）：

# 通過環境變量設置默認代理
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 時使用後備鏈 安全注意事項：後備機制遵循最小權限原則 - 它從不授予隱式的 "允許所有" 訪問權限，僅授予顯式配置的代理的權限。

🔧 技術細節

架構

組件圖

┌─────────────────────────────────────────────────────────┐
│                    代理 / 客戶端                       │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│              Agent MCP 網關                          │
│  ┌───────────────────────────────────────────────────┐  │
│  │  網關工具 (3 個工具, ~2k 令牌)             │  │
│  │  • list_servers                                   │  │
│  │  • get_server_tools                               │  │
│  │  • execute_tool                                   │  │
│  └───────────────────────────────────────────────────┘  │
│                      │                                  │
│  ┌─────────────────────────────────────────────────┐    │
│  │  代理訪問控制中間件                  │    │
│  │  • 提取 agent_id                             │    │
│  │  • 驗證權限                         │    │
│  └─────────────────────────────────────────────────┘    │
│                      │                                  │
│  ┌─────────────────────────────────────────────────┐    │
│  │  策略引擎                                   │    │
│  │  • 先拒絕後允許優先級                 │    │
│  │  • 通配符匹配                            │    │
│  └─────────────────────────────────────────────────┘    │
│                      │                                  │
│  ┌─────────────────────────────────────────────────┐    │
│  │  代理管理器                                   │    │
│  │  • 會話隔離                            │    │
│  │  • 連接池                           │    │
│  └─────────────────────────────────────────────────┘    │
│                      │                                  │
│  ┌─────────────────────────────────────────────────┐    │
│  │  審計日誌記錄器和指標收集器                 │    │
│  └─────────────────────────────────────────────────┘    │
└──────────────────────┬──────────────────────────────────┘
                       │
         ┌─────────────┼─────────────┐
         ▼             ▼              ▼
   ┌─────────┐   ┌─────────┐   ┌─────────┐
   │ 服務器  │   │ 服務器  │   │ 服務器  │
   │   A     │   │   B     │   │   C     │
   │ (stdio) │   │ (stdio) │   │ (HTTP)  │
   └─────────┘   └─────────┘   └─────────┘

請求流程

1. 代理發送請求 到帶有 agent_id 的網關工具
2. 中間件攔截：提取並驗證 agent_id
3. 工具驗證：檢查策略引擎以獲取服務器/工具訪問權限
4. 代理轉發：代理管理器將請求路由到下游服務器
5. 會話隔離：每個請求獲得新的連接
6. 結果返回：透明地轉發到代理
7. 審計記錄：記錄操作並附帶指標

性能特徵

• 上下文減少：90% 以上（2k 令牌 vs 5,000 - 50,000+）
• 增加的延遲：<100ms（P95）
• 網關開銷：每個操作 <30ms
• 會話隔離：每個請求自動隔離
• 併發請求：完全支持

未來功能

M2: 生產環境（計劃中）

🚧 狀態：尚未實現 功能：

• [ ] 網關服務器的 HTTP 傳輸
• [ ] 健康檢查端點
• [ ] 增強的錯誤處理
• [ ] 指標導出 API
• [ ] 連接池優化
• [ ] 速率限制 可用時：

# 使用 HTTP 傳輸運行
export GATEWAY_TRANSPORT=http
export GATEWAY_PORT=8080
uv run python main.py

# 健康檢查端點
curl http://localhost:8080/health

# 指標端點
curl http://localhost:8080/metrics

M3: 開發者體驗（計劃中）

🚧 狀態：尚未實現 功能：

• [ ] 單代理模式（繞過 agent_id 要求）
• [ ] 配置驗證 CLI 工具
• [ ] 帶有示例的 Docker 容器
• [ ] 交互式設置嚮導
• [ ] VS Code 擴展 可用時：

# 單代理模式（無需 agent_id）
export GATEWAY_DEFAULT_AGENT=developer
uv run python main.py

# 驗證配置
uv run python -m src.cli validate

# 使用 Docker 運行
docker run -v ./config:/config agent-mcp-gateway

📄 許可證

本項目根據 MIT 許可證授權 - 有關詳細信息，請參閱 LICENSE 文件。