跳转到主要内容
一个远程 MCP 服务器只是一个你的 智能体在其上调用工具的 HTTP 端点——而它们中的大多数都藏在一个 令牌、一个 OAuth 客户端或 basic auth 后面。当你把那个服务器注册 在 防火墙的 MCP 网关 后面时，你把凭据 交给 OrcaRouter 一次，挑选它如何鉴权，然后网关在派发时注入它。 密钥被静态加密，并且永不传到模型或你的智能体代码。 本页涵盖注册一个服务器的鉴权一侧：四种 auth_mode 形态，以及 你的凭据会发生什么。关于连接建立之后网关对每一次 tools/call 所做的一切——每次调用的策略、命名空间、SSRF 防护——参见 MCP 网关参考。

​
1. 为什么在网关鉴权

没有网关时，每个与一个 MCP 服务器交谈的智能体都携带它自己的那份 该服务器令牌副本，散落在各个配置和提示词里。改为把服务器经过 OrcaRouter 路由，凭据就只存在于恰好一个地方：
  • 每服务器一个存储的密钥。 你在工作区记录上注册凭据一次。 智能体用一个 OrcaRouter 密钥连接到网关——它们永不看到上游 服务器的令牌。
  • 静态加密，读取时屏蔽。 凭据在存储时被加密。每次你通过控制台 或 SDK 读回服务器，密钥都以屏蔽形式回来——没有任何 API 会以 明文返回它。
  • 派发时注入。 网关只在它把一次 tools/call 转发到真实服务器的 那一刻解密凭据，然后把它附加到那次出站请求上。它永不被回传到 模型或客户端。
一个你读不回来的凭据是一个特性，不是一个缺口。因为读取总是被屏蔽， 一个泄露的控制台会话或 SDK 令牌无法外泄你的 MCP 服务器密钥—— 它只能重新指向或轮换它们。

​
2. 挑选一个 auth_mode

每一次服务器注册都携带一个 auth_mode。它是一个由四个值组成的 闭集，决定你在 auth_json 中提供的凭据形态：
服务器是开放的（或按网络信任网关）。把 auth_json 留空。当你不 设置 auth_mode 时这是默认值。
托管 MCP 服务器最常见的情形。提供一个令牌；网关在每次调用上 把它作为一个 bearer 凭据发送。
{ "token": "ghp_…" }
用于受 OAuth 保护的服务器。提供一个你已经铸造的 access_token； 网关把它作为一个 bearer 凭据发送，与 bearer 完全一样。自动的 client-credentials 交换（用一个 client_id/client_secret 换取 一个全新令牌）尚不可用——一个没有 access_token 的 oauth 注册会被拒绝。
{ "access_token": "…" }
HTTP basic auth。
{ "username": "…", "password": "…" }
只要 auth_mode 不是 none，auth_json 就是必填的。用一个空凭据 注册一个 bearer/oauth/basic 服务器会被拒绝——网关不会持久化 一个半配置的连接。

​
3. 注册一个安全的 MCP 服务器 —— 一个例子

MCP 服务器注册是一个控制台操作：它在你的会话/访问令牌下针对 /api/workspace/firewall/mcp_servers 运行，并且写入一个服务器需要 Developer+ 角色。（这不同于你用于 /v1/* 模型调用的 sk-orca-… 中继密钥——那个密钥永不管理工作区配置。） 从防火墙控制台，或直接用你的会话令牌，注册一个 bearer-鉴权 服务器： 
curl https://api.orcarouter.ai/api/workspace/firewall/mcp_servers \
  -H "Authorization: Bearer <your-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github",
    "endpoint": "https://api.githubcopilot.com/mcp",
    "auth_mode": "bearer",
    "auth_json": "{\"token\":\"ghp_x\"}",
    "enabled": true
  }'
name 每工作区唯一（重名返回 HTTP 409），并且它不能包含 . ——那个字符把工具命名为 <server>.<tool>。在进入时，OrcaRouter 加密 auth_json 并只存储密文。当你读回服务器时，你得到屏蔽形式。
在一次更新时把屏蔽值原样回传以保持已存储的密钥不变——只有在你 真的想轮换它时才发送一个真正的 auth_json。关于轮换流程参见 凭据轮换。

​
4. 证明连接有效

鉴权不算完成，直到网关能用你存储的凭据真正到达服务器。 **探测（Probe）**它： 
curl -X POST \
  https://api.orcarouter.ai/api/workspace/firewall/mcp_servers/42/probe \
  -H "Authorization: Bearer <your-session-token>"
网关使用解密后的凭据连接到端点，列出服务器的工具，并记录一个 可达性 status：
status含义
ok已到达并已鉴权；工具已发现。
degraded可达但不完全健康。
down无法连接或鉴权。
注册后紧接着出现的一个 down 结果几乎总是意味着一个坏凭据或 错误的 auth_mode——修正 auth_json 并再次探测。探测是一个 Developer+ 操作；捆绑的进程内服务器没有端点，不可探测。
一个被禁用的服务器是干净的关闭开关：它的工具从网关中消失，它的 凭据永不被解密。在你理顺它的鉴权时禁用一个服务器，然后在一次探测 回到 ok 之后重新启用。

​
5. 从一个智能体读取服务器

你的智能体不读取凭据。当一个 SDK 代理需要运行时注册表时，它用一个 firewall-gateway-scoped 密钥调用 GET /api/v1/firewall/mcp_servers ——一个专用密钥，不是你的中继密钥也不是你的会话。那条路径只提供 已启用的服务器，并且网关仍然端到端地拥有凭据注入。 把一个智能体连接到统一 MCP 端点的内容在 网关参考 中涵盖。

​
6. 下一步去哪里

连接你的第一个服务器

完整的注册演练，从空工作区到一个活的工具。

轮换凭据

在不中断连接的情况下替换一个泄露或将过期的密钥。

允许列表 MCP 工具

决定你的智能体实际上可以调用一个服务器的哪些工具。

限制出站

约束一个服务器的工具在网络上被允许触及哪里。
关于这背后的概念——网关如何坐落在请求路径中，以及为什么凭据 永不触及模型——参见 OrcaRouter 如何检查 和 保护 AI 智能体。关于它所 关闭的威胁，参见 MCP 工具投毒 和 数据外泄。