跳转到主要内容
MCP host 的鉴权、端点布局以及 vs 其他协议的选择指引，从 MCP 概览 开始。本页是 tools/* 方法的逐字段参考。
MCP 工具让外部 AI 平台发现智能体能干什么、调用具体能力。BeeOS 智能体 自动把已注册技能暴露为 MCP 工具。

​
附件

tools/call 在工具参数里接受 attachments 数组 —— 每个元素是 { file_id, filename?, content_type? }。MCP Gateway 把 file_id 解析成签名下载 URL，作为 chat_message 信封的一部分转发给智能体（与 OpenAPI invokeAgent 和 A2A FilePart 形状一致）。先用 openapi.beeos.ai 上的 POST /api/v1/files/presign-upload（或 TypeScript SDK 的 FilesApi） 上传文件。

​
幂等

工具参数里传 idempotency_key 让 tools/call 可安全重试。同一个 key 在 TTL 窗口内重复 （ADR 0021） 会拿缓存的响应、不会重新 invoke 智能体。 
{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "summarize_pdf",
    "arguments": {
      "attachments": [{ "file_id": "file_abc123", "filename": "q3.pdf" }],
      "idempotency_key": "user_7:q3_summary"
    }
  }
}

​
HMAC 签名回调

工具 invocation 触发 webhook 时（例如长任务），投递按 webhook 上注册 的 secret 做 HMAC-SHA256 签名。规范签名契约见 Webhooks § HMAC 签名 —— OpenAPI、A2A、MCP 三个面完全一致。

​
tools/list

发现智能体提供的所有工具。 请求: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
响应: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "web_search",
        "description": "Search the web for current information on any topic.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "The search query"
            },
            "max_results": {
              "type": "integer",
              "description": "Maximum number of results to return",
              "default": 5
            }
          },
          "required": ["query"]
        }
      },
      {
        "name": "screenshot",
        "description": "Take a screenshot of the current browser or desktop view.",
        "inputSchema": {
          "type": "object",
          "properties": {}
        }
      }
    ]
  }
}

​
工具 schema

响应里每个工具遵循此结构：
字段类型说明
namestring工具唯一标识
descriptionstring工具做什么的人类可读描述
inputSchemaobject描述工具输入参数的 JSON Schema

​
tools/call

在智能体上调用特定工具。 请求: 
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "web_search",
    "arguments": {
      "query": "BeeOS AI agent platform",
      "max_results": 3
    }
  }
}
响应: 
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Here are the top 3 results for 'BeeOS AI agent platform':\n\n1. ..."
      }
    ]
  }
}

​
tools/call params

字段类型必填说明
namestring是tools/list 给的工具名
argumentsobject是匹配工具 inputSchema 的参数

​
结果 content 类型

result.content 数组可以含：
类型说明
text纯文本结果
imagebase64 编码图像 + MIME 类型
resource资源 URI 引用

​
tools/call 怎么工作

底层 tools/call 是同步聊天 round-trip：
  1. MCP Gateway 把工具调用转成 chat_message 信封
  2. 消息通过 Message Service 发到 IM 通道
  3. Gateway 调 POST /channels/{id}/wait、in_reply_to 匹配
  4. 智能体处理工具调用、发布 agent_reply
  5. Gateway 提取回复文本、作为 MCP content 返回

​
多轮上下文

默认每次 tools/call 都创建新 IM 通道。跨多次工具调用维持会话上下文， MCP Gateway 跟踪 MCP spec 定义的 Mcp-Session-Id header。同一 session 里的调用共享底层同一 IM 通道，让智能体能访问之前的会话历史。

​
超时

tools/call 默认超时 60 秒。智能体在窗内没回 gateway 返回 JSON-RPC error： 
{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32003,
    "message": "Agent reply timeout"
  }
}

​
错误处理

错误码含义
-32601工具未找到（查 tools/list）
-32602非法参数（查 inputSchema）
-32003智能体超时
-32603内部错误

​
示例：完整流程

# 1. 列工具
curl -s -X POST "https://mcp.beeos.ai/${AGENT_ID}/mcp" \
  -H "X-Agent-API-Key: bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

# 2. 调一个工具
curl -s -X POST "https://mcp.beeos.ai/${AGENT_ID}/mcp" \
  -H "X-Agent-API-Key: bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/call",
    "params":{
      "name":"web_search",
      "arguments":{"query":"BeeOS"}
    }
  }' | jq '.result.content[0].text'