外部 Agent MCP 接入

通过受信任的服务端应用，把 Manager AGI Agent 作为 MCP 工具调用。本文覆盖配置、认证、下游授权、调用、恢复与稳定错误契约。

快速开始

1. 在 Web 管理后台创建并启用第三方应用，绑定公司，复制 App ID 与 App Secret。
2. 给该公司分配已启用的 Agent。只有已启用、已分配且拥有有效已发布 Skill 的 Agent 才会出现。
3. 将 MCP Streamable HTTP 客户端连接到 Engine HTTPS 主机上的 POST|GET|DELETE /openapi/v1/agents/mcp。
4. 初始化会话，发送 notifications/initialized，调用 tools/list，再调用 agent_{id} 工具。

通用助手不会公开。App Secret 必须只保存在服务端。

认证与权限范围

API 环境：

• 测试环境：https://aim-api-test.proton-system.com
• 正式环境：https://aim-api.proton-system.com

每个请求都必须携带 Authorization: Basic Base64(KEY:SECRET)，其中 KEY 是 App ID，SECRET 是 App Secret，同时发送下列内容协商请求头。

Authorization: Basic Base64(KEY:SECRET)
Content-Type: application/json
Accept: application/json, text/event-stream

支持自定义请求头的远程 MCP 客户端可使用以下配置：

{
  "mcpServers": {
    "manager-agi": {
      "url": "https://xxx.com/openapi/v1/agents/mcp",
      "headers": {
        "Authorization": "Basic <Base64(AppID:AppSecret)>"
      }
    }
  }
}

启用的第三方应用在公司范围内获得长期授权：现有和以后新增分配的 Agent、以后发布的 Skill 都会立即可调用，写操作和高风险操作也不需要人工审批。CompanyRole 不会缩小该权限。Engine 仍会检查应用、公司、Agent、分配关系、Skill 发布状态、下游授权、Schema/风险漂移、参数校验、限流、幂等和审计。

初始化与会话管理

使用支持的 MCP 协议版本初始化，并保存响应头 Mcp-Session-Id。

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"partner-server","version":"1.0.0"}}}

{"jsonrpc":"2.0","method":"notifications/initialized"}

后续 POST、GET、DELETE 请求都要携带 Mcp-Session-Id。收到 INVALID_MCP_SESSION 后重新初始化。

Agent 工具与元数据

初始化后发现工具：

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

工具名为 agent_{id}，前缀后的内容是完整 Agent ID。顶层 title 使用 Agent 名称，description 使用 Agent 描述，描述为空时回退到名称。_meta.easyposAgent 只包含公开的 id、name、description、iconUrl。同级的 authorizationRequirements 包含去重后的下游授权要求：mcpHubId、mcpHubName、authType、status、expiresAt、authorized，以及需要授权时由 Engine 生成的 authorizationUrl。Prompt、快捷问题、Skill 定义、内部工具 Schema 和凭据不会公开。

下游授权

当 status 为 MISSING 或 REAUTH_REQUIRED 时，打开 Engine 生成的 authorizationUrl，其路径从 /openapi/v1/mcp/authorization/start 开始。用户完成授权后，第三方应用重试 tools/list 或原来的 tools/call；ACTIVE 表示 Engine 可以使用应用范围内保存的授权执行。授权过期或下游返回 401 时必须重新走同一授权流程；不刷新 Token、不提交下游请求头，也不自动重放失败的业务调用。

调用 Agent

使用 tools/list 返回的准确工具名。需要标准 MCP 进度通知时加入 _meta.progressToken。

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"agent_a441d514-2aed-4b86-b12f-7cce1bd90134","arguments":{"requestId":"req-20260825-001","message":"汇总今天未完成的订单","conversationId":"optional-existing-id"},"_meta":{"progressToken":"req-20260825-001"}}}

requestId 必填、会去除首尾空白，最多 128 个 UTF-8 字节；message 必填，最多 16 KiB；conversationId 可选，只能由同一应用、公司与 Agent 继续使用。

成功结果包含 "status":"COMPLETED"、"answer"、requestId、conversationId、Agent 展示信息和最新 authorizationRequirements。下游凭据缺失时返回 isError:true、status:"authorization_required"、errorCode:"MCP_AUTHORIZATION_REQUIRED"，且不会创建执行请求。

SSE、恢复、取消与关闭

使用 Accept: application/json, text/event-stream 接收标准 MCP 进度通知和一个最终工具结果。流中断后，使用 Basic 认证向同一端点发送 GET，并携带 Mcp-Session-Id、不透明的 Last-Event-ID、EasyPOS-Agent-Request-Id、EasyPOS-Agent-Id 和 Accept: text/event-stream。恢复只读取持久化事件，不会重新执行 Agent；若仍有后续事件，使用最新游标继续 GET。

显式 MCP 取消只会请求取消，已经派发的副作用不会回滚。transport disconnect 不会取消已经接受的执行。使用带 Basic 与 Mcp-Session-Id 的 DELETE 关闭会话。

限制与幂等

requestId 在单个应用内保持 90 天幂等。相同规范化输入会重放已保存或进行中的结果，不再消耗执行额度；输入不同返回 IDEMPOTENCY_CONFLICT，仍在运行时可能返回 REQUEST_IN_PROGRESS。

错误契约

传输层错误使用 HTTP 状态码和类似 {"code":"COMPANY_INACTIVE","description":"The company is inactive."} 的 JSON。MCP/领域错误在结构化工具结果中返回 isError:true、errorCode 与 errorDescription。描述是稳定且不含敏感信息的英文文本，程序分支应以错误码为准。

安全与排障

使用 TLS，在密钥管理系统保存 App Secret，并从日志中脱敏授权请求头。不要通过浏览器/移动端代码、URL 或源码仓库发送 Secret。服务端应用应省略 Origin；若发送，必须是允许的 HTTPS Origin。怀疑泄露时停用应用或重置 Secret，已有会话会随即失效。

若 tools/list 为空，检查公司/Agent 状态、分配关系和有效已发布 Skill。若需要授权，打开 authorizationUrl，完成后重试发现或调用；会话无效时重新初始化。应用的通知 callbackUrl 不是 Agent 结果通道，执行结果应从 MCP/SSE 读取。