代理-mcp网关
项目介绍
Agent MCP Gateway
<!-- mcp-name: io.github.roddutra/agent-mcp-gateway -->一个模型上下文协议（MCP）网关，聚合多个MCP服务器，并提供基于策略的代理和子代理访问控制。通过按需工具发现而不是在启动时加载所有工具定义，解决了Claude Code的MCP上下文窗口浪费问题。
<a href="https://glama.ai/mcp/servers/@roddutra/agent-mcp-gateway"> <img width="380" height="200" src="https://gips1.baidu.com/it/u=2350862516,2380795380&fm=3081&app=3081&f=PNG?w=760&h=200" /> </a>状态
- ✅ M0: 基础 - 配置、策略引擎、审计日志、
list_servers工具 - ✅ M1: 核心 - 代理基础设施、
get_server_tools、execute_tool、中间件、指标、热重载、OAuth支持 - 🚧 M2: 生产 - HTTP传输、健康检查（计划中）
- 🚧 M3: 开发者体验 - 单代理模式、配置验证CLI、Docker（计划中）
当前版本: M1-核心完成（含OAuth）
目录
概述
问题
当多个MCP服务器配置在开发环境中（如Claude Code、Cursor、VS Code），所有服务器的工具定义都会加载到每个代理和子代理的上下文窗口中：
- 启动时消耗5,000-50,000+个令牌
- 超过80-95%的已加载工具从未被单个代理使用
- 实际工作所需的上下文被浪费在未使用的工具定义上
解决方案
Agent MCP网关作为一个单一的MCP服务器，根据可配置的每代理规则代理到多个下游MCP服务器：
- 3个网关工具在启动时加载（约2k令牌）
- 代理按需发现并请求特定工具
- 超过90%的上下文减少
- 每个代理/子代理的基于策略的访问控制
工作原理
网关位于代理和下游MCP服务器之间，仅暴露3个轻量级工具。当代理需要特定功能时，它会通过网关发现可用的服务器和工具，网关根据策略规则过滤可见性——代理只能看到它们有权限访问的服务器和工具。这将每个代理的上下文窗口减少到仅相关的工具，而网关处理授权请求到下游服务器的代理。
查看带有示例的详细图解 →（包括下游服务器、工具和网关规则示例）
主要特点
- ✅ 按需工具发现 - 只在需要时加载工具定义
- ✅ 每代理访问控制 - 配置每个代理可以访问哪些服务器/工具
- ✅ 易于代理集成 - 简单模板以添加对任何代理的支持（参见指南）
- ✅ 先拒绝后允许策略 - 显式拒绝规则优先
- ✅ 通配符支持 - 工具名称的模式匹配（
get_*，*_user） - ✅ 会话隔离 - 并发请求不会相互干扰
- ✅ 透明代理 - 下游服务器不知道网关的存在
- ✅ 审计日志 - 所有操作都被记录用于监控
- ✅ 性能指标 - 追踪每个代理/操作的延迟和错误率
- ✅ 热配置重载 - 更新规则/服务器无需重启
- ✅ 线程安全操作 - 在重新加载期间安全并发访问
- ✅ 诊断工具 - 通过
get_gateway_status进行健康监控（仅调试模式）
安装
# 创建 ~/.config/agent-mcp-gateway/ 并生成模板配置文件
uvx agent-mcp-gateway --init
这将生成两个准备自定义的模板文件：
mcp.json- 您的下游MCP服务器（如Brave、Postgres等）mcp-gateway-rules.json- 每代理访问策略（谁可以使用哪些服务器/工具）
对于本地开发： 请参阅开发部分。
快速开始
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"
}
}
}
}
注意： 如果使用默认配置位置，则环境变量是可选的。参见环境变量参考了解所有选项。
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 替换为您代理的标识符（例如，“研究员”，“后端”，“管理员”）。
示例： 参见.claude/agents/researcher.md和.claude/agents/mcp-developer.md以获取完整的配置示例。
方法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——网关将自动使用您配置的默认代理。
命令行选项
# 显示版本
agent-mcp-gateway --version
# 初始化配置目录（首次设置）
agent-mcp-gateway --init
# 启用调试模式（公开get_gateway_status诊断工具）
agent-mcp-gateway --debug
# 显示帮助
agent-mcp-gateway --help
配置文件发现
网关按照以下顺序搜索配置文件：
MCP服务器配置（.mcp.json）
GATEWAY_MCP_CONFIG环境变量（如果设置）- 当前目录下的
.mcp.json - 用户主目录下的
~/.config/agent-mcp-gateway/.mcp.json - 备用目录下的
./config/.mcp.json
网关规则（.mcp-gateway-rules.json）
GATEWAY_RULES环境变量（如果设置）- 当前目录下的
.mcp-gateway-rules.json - 用户主目录下的
~/.config/agent-mcp-gateway/.mcp-gateway-rules.json - 备用目录下的
./config/.mcp-gateway-rules.json
提示： 使用 agent-mcp-gateway --init 在首次运行时创建主目录配置。
配置
网关需要两个配置文件：
1. MCP服务器配置
文件： mcp.json（搜索多个位置）
定义网关将代理到的下游MCP服务器。使用与Claude Code和其他编码代理兼容的标准MCP配置格式：
{
"mcpServers": {
"brave-search": {
"description": "通过Brave搜索引擎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等应用，在您的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"
}
}
}
}
（如果您直接在 .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
}
}
代理示例解释：
研究员 - 展示隐式授权 + 显式允许：
brave-search：仅brave_web_search工具（显式允许缩小访问范围）context7：所有工具（隐式授权 - 允许服务器，未指定工具规则）
后端 - 展示通配符允许与先拒绝后允许优先级：
postgres：仅query、list_tables、list_schemas（显式允许）；拒绝规则作为安全网laravel-boost：通配符允许（get_*、list_*、read_*、database_*、search_*）授予广泛访问，但database_query尽管匹配database_*通配符仍被显式拒绝（拒绝优先），tinker被阻止作为安全措施
管理员 - 展示服务器通配符 + 混合访问模式：
notion：拒绝（服务器级别拒绝覆盖通配符服务器允许）brave-search：仅brave_web_search（一个服务器上的显式限制）playwright：所有工具除了browser_type（隐式授权与显式拒绝）- 其他所有服务器：所有工具（隐式授权 - 无工具规则指定）
Claude Desktop - 展示隐式授权与多种拒绝类型：
context7、brave-search、notion：所有工具（隐式授权）playwright：所有工具除了browser_type、browser_close_all和匹配launch_*的工具（隐式授权与显式 + 通配符拒绝）
默认 - 最小特权原则：
- 当未提供
agent_id且deny_on_missing_agent为false时作为回退使用 - 默认拒绝所有服务器；使用
GATEWAY_DEFAULT_AGENT环境变量指定不同的默认代理
策略优先级顺序：
- 显式拒绝规则（最高优先级）
- 通配符拒绝规则
- 显式允许规则
- 通配符允许规则
- 隐式授权（如果代理有服务器访问权限但没有
allow.tools.{server}条目） - 默认策略（拒绝）
隐式授权行为：
- 如果代理有服务器访问权限且没有
allow.tools.{server}条目，则该服务器的所有工具将隐式授权 allow.tools.{server}条目将访问范围缩小到指定的工具deny.tools.{server}条目过滤掉特定工具（在步骤1-2中评估）- 规则是服务器特定的，不影响其他服务器
配置灵活性：
- 规则可以引用当前不在
.mcp.json中的服务器 - 未定义的服务器引用被视为