MCP 网关
把多个 MCP 服务器聚合成一个地址,按令牌决定谁能用哪些服务器
MCP 网关把你用到的多个 MCP 服务器合成一个地址:客户端只配一个 MCP 服务器(Astra),Astra 替它去连后面的各个上游,并用令牌决定哪个令牌能用哪些服务器。
功能默认关闭:关闭时 /mcp 返回 404,不会多出任何入口。
快速开始
- 打开左侧的「MCP 网关」,打开「启用 MCP 网关」。
- 点「添加服务器」,填名称和地址(
https://…/mcp)。需要凭据时选「请求头」或「OAuth」,见下文。 - 点「测试连接」。成功会显示这个服务器说的协议版本和它的工具数;失败会给出原因(不会显示上游的地址)。
- 打开「令牌」页,编辑要用 MCP 的令牌,在「MCP 服务器」里勾选它能用的服务器。没有勾选的令牌用不了 MCP。
- 把聚合地址和令牌配进客户端,例如 Claude Code:
命令bash
令牌放在 Authorization: Bearer 或 x-api-key 请求头里,不接受放在地址的查询参数中(地址会进日志)。
两个地址
标识由名称生成(可在服务器设置里改)。它出现在工具名里,客户端的工具白名单会用到,所以发布后不要随意改。工具的顺序固定(先标识、再工具名),客户端和提示词缓存每次看到同一份列表。
一个令牌看不到没有绑定给它的服务器;调用没绑定的工具和调用不存在的工具得到同样的错误,不会泄露哪些服务器存在。
应用到客户端
页面上的 应用到客户端 把 /mcp 地址和一个令牌写进 Claude Code 或 Codex 自己的 MCP 配置,不用手工拷贝:
- 只列出已经绑定了 MCP 服务器、且启用的令牌;令牌的密钥由服务器直接写入客户端文件,不经过浏览器,接口也不会返回它;
- 写入和移除只能在本机操作。第一次写入前的文件会备份(和客户端接管网关用的是同一套备份与还原规则),移除时还原成写入前的样子,没有别的残留;
- 不会覆盖不是 Astra 写的
astra条目(状态显示「冲突」),请先改名或删除它。Astra 写入之后被改动的条目显示「已被改动」,只有你选择「覆盖并重新写入」才会替换,「强制移除」才会删掉; - 这个条目和客户端的「接管网关」开关各自独立:关闭接管不会删掉它,
astra-server restore-all会把它一并移除; - 网关关闭时(上面的开关)客户端会得到 404,页面会提示;写入后需要重启客户端;
- 网关只转发 http 类型的 MCP 服务器,本机上的 stdio 服务器不在其中,也不会被写进客户端。
协议
MCP 现在有两代协议,Astra 两边都能说,客户端和上游各用各的:
另外:
- 已弃用的 HTTP+SSE(2024-11-05):作为入口不支持;作为上游可以选「旧版 SSE」,只在服务器只支持它时使用。
- stdio(本机子进程)的服务器不支持:Astra 不会替你启动程序。
- 回复总是 JSON,没有请求范围的 SSE(进度通知暂不转发)。
- 服务器在调用中途向客户端要采样或确认(sampling / elicitation)这类需要往返交互的请求,无状态的网关无法转发;这次调用会返回「需要交互」的错误。
只在新版上游上发现的 input_required 会原样交给新版客户端;旧版客户端不会重试,所以对它们会变成一次工具错误。
上游的认证
OAuth 授权
- 授权按 MCP 规范和 OAuth 2.1 做:发现授权服务器、注册客户端(需要时动态注册)、PKCE、带上
resource,并校验授权响应里的iss,不匹配会在花掉授权码之前就被拒绝。 - 授权只能在运行 Astra 的这台机器上发起(来自其它机器或隧道的管理请求会被拒绝),回调地址是
<网关地址>/api/mcp/oauth/callback,本机就是http://127.0.0.1:<端口>/api/mcp/oauth/callback(端口以实际监听的为准,每次授权按当前端口注册)。所以在 Docker 或远程服务器上运行 Astra 时无法做 OAuth 授权,请改用「请求头」方式,或在本机完成授权。 - 令牌(访问令牌、刷新令牌、客户端注册信息)加密保存,不会出现在接口返回、日志或错误信息里。把服务器指到另一个地址会清除已保存的令牌:授权不会被发给它没被授予过的地址。
- 没有授权的 OAuth 服务器,数据面请求不会去连授权服务器,只会得到「需要授权」。需要重新授权时,用「重新授权」;想撤销用「忘记授权」。
服务器状态
一个服务器出问题时,它的工具从列表里消失,其他服务器不受影响。对它的调用返回「工具没有运行」的错误结果,文字里不含上游的地址。带副作用的调用连接中断后不会自动重试(它可能已经生效)。
安全
- 只认令牌头:
Authorization: Bearer或x-api-key。令牌停用后立即失效。 - Origin 检查:浏览器发来的请求带
Origin头,不在「允许的浏览器来源」里就返回 403(防 DNS 重绑定);非浏览器客户端不带这个头,不受影响。 - 添加、修改、测试和授权服务器只能在本机操作:它会让 Astra 去连你指定的地址。远程管理员可以查看、删除和调整令牌绑定,不能新增或改地址。
- 不透传令牌:你的 Astra 令牌不会发给上游,上游只会看到 Astra 为它保存的凭据。
- 请求体最大 4 MB;只接受
POST、Content-Type: application/json。
调用记录
页面底部的「最近的调用」列出谁(令牌)调用了哪个服务器的哪个工具、耗时和结果,并标出调用方说的是新版还是旧版协议。不记录参数和返回内容,保留 30 天,和请求日志、链路追踪是分开的。