MCP Gateway

​

1. 端点位置

​

2. 认证 —— 三种凭证、同一个端点

​

2.1 OAuth 2.1 流程（规范合规的 MCP 客户端）

1. 客户端 POST /oauth/register → {client_id, …}。
2. 客户端打开浏览器到 /oauth/authorize?client_id=…&code_challenge=…&redirect_uri=…&state=…。
3. MCP Gateway 重定向到 BeeOS Web 登录 （MCP_WEB_LOGIN_URL/mcp-login?return_to=…）。
4. 用户登录 BeeOS，选择授权哪些智能体。
5. Web 应用回调 MCP Gateway，网关再以 ?code=…&state=… 重定向到 redirect_uri。
6. 客户端 POST /oauth/token 带 code_verifier → access token。
7. 此后客户端用该 token 调 /{agentId}/mcp。

• 你的 BeeOS 账号至少有一个 MCP-enabled 智能体 （mcp_enabled=true）。在 OpenAPI 接入面 GET /api/v1/agents 里 查 —— catalog 响应里有 mcp_enabled 字段。
• 客户端的 redirect_uri 浏览器能达 —— authorization-code 重定向 到不可路由的 host 行不通。
• 本地开发：网关 env 里要有 MCP_PUBLIC_URL=http://localhost:8094， 并且 localhost:3000 的 web 应用要暴露 /mcp-login 路由。

​

2.2 仅 API Key 流程（n8n、脚本、CI）

# n8n / CI: 列出该用户的 MCP-enabled 智能体
curl -X POST https://mcp.beeos.ai/<agentId>/mcp \
  -H "Authorization: Bearer oag_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 绑定到单个智能体的第三方 app
curl -X POST https://mcp.beeos.ai/<agentId>/mcp \
  -H "X-Agent-API-Key: bak_XXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

• Key 绑定到一个智能体 —— 丢失只泄露这一个集成，不连累整个用户账号。
• 可独立于你的 oag_ Key 吊销。
• 智能体拥有者（你）显式签发，同意可审计追溯。

​

3. 各 MCP 方法做什么

​

3.1 initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "clientInfo": { "name": "claude-desktop", "version": "0.7.0" }
  }
}

​

3.2 tools/list

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

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "agent_abc123",
        "description": "Analyze CSV files and produce a chart.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "message": { "type": "string" },
            "context_id": { "type": "string" }
          },
          "required": ["message"]
        }
      }
    ]
  }
}

​

3.3 tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "agent_abc123",
    "arguments": {
      "message": "What's the top-selling SKU last week?",
      "context_id": "ctx-uuid-optional"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text", "text": "Top SKU last week: BLUE-42 (1,329 units)" }
    ]
  }
}

​

3.4 tools/call 取消

​

4. 行为契约 —— MCP 保证什么、不保证什么

• tools/list 是只读且幂等。跨重连重复调用安全。
• tools/call 每个 JSON-RPC ID 始终投递恰好一次 result（或一次 error）。服务端触发的取消（deadline、智能体崩溃）以 JSON-RPC error 带一个稳定 code 形式暴露，详见 错误参考。
• 通过 OpenAPI / A2A 触达的同一智能体在此处也能触达；响应是字节 一致的（来自同一 Message Service 通道的同一 agent_reply）。
• 幂等：传 params.arguments.idempotency_key，网关在底层 L0 invoke 上尊重它。见 调用智能体 § 幂等。
• 附件：传 params.arguments.attachments[] 里的 file_id（来自 POST /api/v1/files/presign-upload）。智能体看到正常的多部分 chat_message。

• 持久异步 —— MCP tools/call 是 request-response。需要在 客户端断开后存活的长任务属于 OpenAPI tasks。想用 “fire-and-forget MCP tool” 通常是协议错配的信号。
• 单次调用内多轮 —— 每次 tools/call 是一个新回合。要串联相关 回合，MCP 宿主通常把会话上下文留在客户端，在下一条 message 里包进相关历史。如果你需要服务端会话连续性，用 OpenAPI 会话接入面，把 conversation ID 透传 到 MCP 调用的 arguments.context_id。
• Webhook push —— MCP 对调用以外的服务端 push 事件没有概念。 “任务完成通知我”的语义用 OpenAPI Webhook（P2-A，参见 Webhook 指南）。
• 限流可见性 —— 网关按凭证 × 智能体强制限流，但限流元数据以 标准 MCP error 形状（code、message）返回。看 code （rate_limited）做退避；wire 上目前不带 Retry-After。

​

5. 常见失败模式

​

6. 端到端示例 —— Claude Desktop

{
  "mcpServers": {
    "beeos-csv-analyst": {
      "transport": "streamable-http",
      "url": "https://mcp.beeos.ai/agent_abc123/mcp"
    }
  }
}

​

7. 另请参阅

• 选择协议 —— MCP 何时是合适的 接入面（对比 OpenAPI / A2A）。
• 认证与 API Key —— oag_ / bak_ / OAuth 生命周期、scope、轮换。
• 错误参考 —— MCP error 信封可返回的稳定 wire 码。
• 公开架构总览 —— MCP 与另外 两个调用方接入面的关系。
• backend/services/mcp-gateway/README.md —— 服务侧 README（env vars、本地开发、部署）。
• MCP Authorization Spec —— 网关实现的 OAuth / DCR / PKCE 规范。