Astra GateEnglish

MCP 网关

把多个 MCP 服务器聚合成一个地址,按令牌决定谁能用哪些服务器

MCP 网关把你用到的多个 MCP 服务器合成一个地址:客户端只配一个 MCP 服务器(Astra),Astra 替它去连后面的各个上游,并用令牌决定哪个令牌能用哪些服务器。

功能默认关闭:关闭时 /mcp 返回 404,不会多出任何入口。

快速开始

  1. 打开左侧的「MCP 网关」,打开「启用 MCP 网关」。
  2. 点「添加服务器」,填名称和地址(https://…/mcp)。需要凭据时选「请求头」或「OAuth」,见下文。
  3. 点「测试连接」。成功会显示这个服务器说的协议版本和它的工具数;失败会给出原因(不会显示上游的地址)。
  4. 打开「令牌」页,编辑要用 MCP 的令牌,在「MCP 服务器」里勾选它能用的服务器。没有勾选的令牌用不了 MCP。
  5. 把聚合地址和令牌配进客户端,例如 Claude Code:
命令bash
claude mcp add --transport http astra http://127.0.0.1:17321/mcp \
  --header "Authorization: Bearer sk-astra-…"

令牌放在 Authorization: Bearer 或 x-api-key 请求头里,不接受放在地址的查询参数中(地址会进日志)。

两个地址

地址内容
/mcp令牌绑定的所有服务器的工具。工具名加上服务器的标识作前缀:<标识>__<工具>,例如 github__search_issues。不同服务器常有同名工具,前缀让它们并存
/mcp/<标识>只有这一个服务器的工具,不加前缀。适合只想让客户端经 Astra 鉴权访问某一个服务器的场景

标识由名称生成(可在服务器设置里改)。它出现在工具名里,客户端的工具白名单会用到,所以发布后不要随意改。工具的顺序固定(先标识、再工具名),客户端和提示词缓存每次看到同一份列表。

一个令牌看不到没有绑定给它的服务器;调用没绑定的工具和调用不存在的工具得到同样的错误,不会泄露哪些服务器存在。

应用到客户端

页面上的 应用到客户端 把 /mcp 地址和一个令牌写进 Claude Code 或 Codex 自己的 MCP 配置,不用手工拷贝:

客户端写入的位置
Claude Code~/.claude.json(设置了 CLAUDE_CONFIG_DIR 时在该目录下)顶层 mcpServers 里的 astra,type 为 http,Authorization 请求头带令牌
Codex~/.codex/config.toml(遵循 CODEX_HOME)里的 [mcp_servers.astra],带 url 和 http_headers 里的 Authorization
  • 只列出已经绑定了 MCP 服务器、且启用的令牌;令牌的密钥由服务器直接写入客户端文件,不经过浏览器,接口也不会返回它;
  • 写入和移除只能在本机操作。第一次写入前的文件会备份(和客户端接管网关用的是同一套备份与还原规则),移除时还原成写入前的样子,没有别的残留;
  • 不会覆盖不是 Astra 写的 astra 条目(状态显示「冲突」),请先改名或删除它。Astra 写入之后被改动的条目显示「已被改动」,只有你选择「覆盖并重新写入」才会替换,「强制移除」才会删掉;
  • 这个条目和客户端的「接管网关」开关各自独立:关闭接管不会删掉它,astra-server restore-all 会把它一并移除;
  • 网关关闭时(上面的开关)客户端会得到 404,页面会提示;写入后需要重启客户端;
  • 网关只转发 http 类型的 MCP 服务器,本机上的 stdio 服务器不在其中,也不会被写进客户端。

协议

MCP 现在有两代协议,Astra 两边都能说,客户端和上游各用各的:

新版(2026-07-28)旧版 Streamable HTTP(2025-11-25 及更早)
握手与会话没有。每个请求自带协议版本和客户端能力(params._meta),HTTP 头 MCP-Protocol-Version、Mcp-Method、Mcp-Name 必须与请求体一致initialize 握手;Astra 不签发会话 ID(规范允许),之后每个请求独立处理
作为入口(客户端 → Astra)支持支持
作为上游(Astra → 服务器)支持,自动识别支持,自动识别,Astra 会为这个上游维持它的会话并在过期时重连

另外:

  • 已弃用的 HTTP+SSE(2024-11-05):作为入口不支持;作为上游可以选「旧版 SSE」,只在服务器只支持它时使用。
  • stdio(本机子进程)的服务器不支持:Astra 不会替你启动程序。
  • 回复总是 JSON,没有请求范围的 SSE(进度通知暂不转发)。
  • 服务器在调用中途向客户端要采样或确认(sampling / elicitation)这类需要往返交互的请求,无状态的网关无法转发;这次调用会返回「需要交互」的错误。

只在新版上游上发现的 input_required 会原样交给新版客户端;旧版客户端不会重试,所以对它们会变成一次工具错误。

上游的认证

方式说明
无上游不需要凭据
请求头例如 Authorization: Bearer … 或 X-Api-Key。值加密保存,保存后不再显示;编辑时留空表示保持原值。Host、Content-Type、Mcp-* 等由网关自己设置的头不能填
OAuth上游是需要登录的服务(如 GitHub、Notion 的官方远程 MCP)。点「授权」,在浏览器里登录并同意,Astra 保存并自动续期令牌

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 服务器,数据面请求不会去连授权服务器,只会得到「需要授权」。需要重新授权时,用「重新授权」;想撤销用「忘记授权」。

服务器状态

状态含义
未检测还没连过
正常上一次连接和调用成功
需要授权OAuth 从未授权、令牌失效且无法续期,或上游要求更多权限(insufficient_scope)。由管理员在界面重新授权;数据面不会自己发起
凭据被拒绝上游拒绝了保存的请求头
无法连接网络不通、超时或上游返回了无法处理的响应
协议版本不支持上游说的版本 Astra 不支持

一个服务器出问题时,它的工具从列表里消失,其他服务器不受影响。对它的调用返回「工具没有运行」的错误结果,文字里不含上游的地址。带副作用的调用连接中断后不会自动重试(它可能已经生效)。

安全

  • 只认令牌头:Authorization: Bearer 或 x-api-key。令牌停用后立即失效。
  • Origin 检查:浏览器发来的请求带 Origin 头,不在「允许的浏览器来源」里就返回 403(防 DNS 重绑定);非浏览器客户端不带这个头,不受影响。
  • 添加、修改、测试和授权服务器只能在本机操作:它会让 Astra 去连你指定的地址。远程管理员可以查看、删除和调整令牌绑定,不能新增或改地址。
  • 不透传令牌:你的 Astra 令牌不会发给上游,上游只会看到 Astra 为它保存的凭据。
  • 请求体最大 4 MB;只接受 POST、Content-Type: application/json。

调用记录

页面底部的「最近的调用」列出谁(令牌)调用了哪个服务器的哪个工具、耗时和结果,并标出调用方说的是新版还是旧版协议。不记录参数和返回内容,保留 30 天,和请求日志、链路追踪是分开的。

管理接口

接口说明
GET / PUT /api/mcp/settings开关、允许的浏览器来源、聚合地址
GET / POST /api/mcp/servers,GET / PATCH / DELETE /api/mcp/servers/{id}服务器(POST、PATCH 仅限本机)
POST /api/mcp/servers/{id}/test测试连接(仅限本机)
POST /api/mcp/servers/{id}/oauth/start、DELETE /api/mcp/servers/{id}/oauth发起授权(仅限本机)、忘记授权
GET /api/mcp/calls最近的调用
PATCH /api/tokens/{id} 的 mcpServers令牌可以使用的服务器 id
GET /api/clients/mcp、GET / POST / DELETE /api/clients/{kind}/mcp客户端里的网关条目:状态、写入({ tokenId, force })、移除(?force=true);kind 为 claude-code 或 codex,POST、DELETE 仅限本机