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 文件。