Unified AI System MCP Gateway

Unified AI System MCP 服务

通过 stdio 或 MCP Streamable HTTP，将 Codex 和其他 MCP 主机连接到无需凭据的 Unified AI System 预览版。

服务会自动启动一个隔离的本地网关，将其固定到确定性的模拟提供方，提供经过身份验证且受权限范围限制的工具，并在 MCP 会话结束时移除网关。它不会启用或授权真实提供方调用。

工具

工具	行为
gateway_health	检查网关健康状态和提供方安全状态。
gateway_readiness	检查首次运行和聊天就绪状态。
agent_governance_status	当经过身份验证的身份具有平台状态访问权限时，检查 Agent Governance 状态。
agent_governance_list	仅列出经过身份验证的租户可见的受治理 Agent。
agent_governance_describe	仅当某个 Agent 属于经过身份验证的租户时，描述该 Agent。
gateway_prompt_enhance	在本地整理自然语言请求，不调用提供方。
gateway_prompt_enhance_llm	通过可选的 LLM 后端增强提示词（后端不可用时则回退）。
gateway_chat	发送一条仅使用模拟提供方的聊天请求。
knowledge_readiness	检查本地知识基础设施。
knowledge_retrieve	按关键词搜索本地知识库。
workflow_health	检查受治理的工作流子系统。
workflow_actions	列出工作流操作定义。
workflow_run	执行一个包含三个步骤的本地工作流，并以原子方式发布按租户分区的构件。托管模式会注入专用的 file_write Agent；外部受治理网关需要提供 agentId。
workforce_health	检查 workforce 子系统。
workforce_agents	列出 workforce Agent 描述信息。

Agent Governance 检查工具为只读工具。workflow_run 会写入一个受控的本地构件。由于 MCP 工具协议目前无法在传输超时后证明生成操作具有幂等性且可安全取消，因此 Agent 创建仍可通过 REST、共享 SDK 和人工操作的 Agent Console 提供。MCP 工具不会提供 Agent 创建／执行／撤销、批准／拒绝或策略创建／激活功能。治理工具绝不接受 tenantId 或 ownerUserId：网关会根据经过身份验证的身份绑定这两个值，跨租户描述请求则会以未找到的方式失败。workflow_run 绝不会覆盖已有路径；如果连接的网关启用了该控制平面，则该操作会经由 Agent Governance 路由。聊天工具会在每次请求前检查网关安全状态；除非 realProviderEnabled 的值严格为 false，且响应能证明 executionMode: "fake"，否则会以失败关闭。

源代码构建版本会公开十六个工具，包括四个 Agent Governance 生命周期工具和无需提供方调用的 gateway_prompt_enhance 预览版。已发布的镜像会公开其固定标签所包含的工具集。

从源代码运行

在仓库根目录中运行：

pnpm install --frozen-lockfile
node packages/mcp-server/src/index.js

项目级 .codex/config.toml 会在受信任的 Codex 项目中自动注册该命令。克隆仓库或更改 MCP 配置后，请重启 Codex，然后使用 /mcp 检查该服务。

Streamable HTTP

启动源代码构建版 HTTP 传输：

pnpm mcp:http

MCP 端点为 http://127.0.0.1:3210/mcp。默认情况下，它仅监听环回地址，会验证 Host 和 Origin，启动相同的伪提供方网关，并公开与 stdio 相同的 16 个源代码构建版工具。将任何 MCP Streamable HTTP 客户端指向该 URL 即可。

如需在本地使用受令牌保护的端点，请设置 MCP_HTTP_AUTH_TOKEN，并将其作为 Authorization: Bearer <token> 发送。除非以下变量全部存在，否则绑定到环回地址以外的地址会失败关闭：

变量	要求
MCP_HTTP_HOST	非环回绑定地址，例如 0.0.0.0。
MCP_HTTP_AUTH_TOKEN	至少 32 字节；切勿将其放入源代码管理。
MCP_HTTP_ALLOWED_HOSTS	以逗号分隔的请求主机名，不含端口。
MCP_HTTP_ALLOWED_ORIGINS	以逗号分隔的浏览器来源主机名，不含协议或端口。

通过 TLS 反向代理进行私有部署的示例：

MCP_HTTP_HOST=0.0.0.0 \
MCP_HTTP_AUTH_TOKEN=replace-with-a-random-secret-of-at-least-32-bytes \
MCP_HTTP_ALLOWED_HOSTS=mcp.example.com \
MCP_HTTP_ALLOWED_ORIGINS=console.example.com \
pnpm mcp:http

内置的 Bearer 令牌是一种有边界的自托管控制机制，并非 OAuth 授权服务器。请在受信任的反向代理处终止 TLS，并在向不受信任的网络公开端点之前使用专用身份层。已发布的 v0.5.0 容器仍仅支持 stdio；上述 HTTP 命令属于源代码构建版功能，之后的版本才会发布该功能。

使用 Docker 添加到 Codex

无需克隆项目，也无需 API 密钥：

codex mcp add unified-ai-system -- docker run --rm -i ghcr.io/happy520ai/unified-ai-system/mcp-server:0.8.0

专用镜像默认启动 MCP 服务；无需覆盖命令，并且会直接调用 Node，以免包管理器的输出污染 JSON-RPC 流。其 OCI 身份和 stdio 传输已在仓库根目录的 server.json 中声明，供官方 MCP Registry 使用。

等效的 config.toml 条目如下：

[mcp_servers.unified_ai_system]
command = "docker"
args = [
  "run",
  "--rm",
  "-i",
  "ghcr.io/happy520ai/unified-ai-system/mcp-server:0.8.0",
]
startup_timeout_sec = 45
tool_timeout_sec = 60
default_tools_approval_mode = "writes"

对于接受标准 JSON mcpServers 结构的客户端，请参阅通用 MCP 客户端配置指南。

在 Codex 中试用

添加服务后重启 Codex，然后运行 /mcp verbose 检查已连接的工具。可以先尝试以下任务：

使用 gateway_prompt_enhance 将“为我的团队构建一个小型 API”改写为 编码提示词。展示保留的原始请求、检测到的语言、 增强后的提示词，以及未调用任何提供方的证明。

然后验证伪聊天安全边界：

使用 Unified AI System MCP 工具检查网关的健康状况和就绪状态， 只有在网关证明处于纯伪模式时，才通过网关聊天发送 MCP_READY。 报告提供方、模型、执行模式和响应。

60 秒 Codex MCP 快速入门 还包含另外两个安全任务、预期证据、诊断信息和移除命令。

连接到现有的安全网关

设置 AI_GATEWAY_MCP_URL 和专用网关访问令牌，即可使用已在运行的实例：

AI_GATEWAY_MCP_URL=http://127.0.0.1:3100 \
AI_GATEWAY_MCP_AUTH_TOKEN=<at-least-32-character-gateway-token> \
node packages/mcp-server/src/index.js

受管网关使用私有的最小权限令牌，其有效期受隔离子进程的生命周期限制；该令牌绝不会出现在 MCP 结果中。外部网关启动时，如果令牌缺失或强度不足、URL 中包含凭据、使用非环回明文 HTTP、身份验证无效，或网关可能调用真实提供方，都会被拒绝。提供方凭据和真实提供方执行仍不属于此预览功能的范围。

对于 Agent Governance，除非明确需要更广泛的操作员工作流，否则只向专用 Gateway 身份授予 dashboard:read 和 workflow:run。agent_governance_status 还需要 Gateway 的平台租户身份；普通租户仍可使用租户范围内的 list、generate 和 describe。切勿仅为使用这些工具，就向 MCP 模型授予 workflow:approve 或 user:admin。

验证

测试通过官方 MCP v2 客户端启动两种传输方式。测试固定使用现代的 2026-07-28 无状态时代的 stdio 和 Streamable HTTP，保留与旧版 2025-11-25 及 2025-06-18 的初始化兼容性，列出所有源代码构建工具，验证本地提示词增强和模拟提供方安全性，测试 HTTP/CORS 访问控制，关闭客户端，并确认每个受管网关均已停止。容器安全的原始冒烟测试还使用 server/discover 和逐请求的 _meta 封装，而非根据 SDK 版本推断是否支持现代功能：

pnpm verify:mcp