MCP 文档

阅读当前文档内容。

文档
本页目录

MCP 接入文档

定位

MCP 是账号级智能运营入口。POST /mcp 只接受账号级 MCP Bearer 密钥，所有工具统一按账号授权。机器人 API 密钥继续用于原有 HTTP API，但不再接入 MCP，避免 Agent 同时看到两套相近的工具。

接入


POST https://qw.huokeshi.cn/mcp

Authorization: Bearer <secret>

Accept: application/json, text/event-stream

Content-Type: application/json

账号级密钥在后台账号首页的“ MCP 接入”模块生成，也可以轮换。轮换后旧密钥立即失效。鉴权本身是只读操作，不会自动创建机器人。

账号级工具

账号级工具从 Bearer 密钥解析账号，不接受 reg_token 参数。所有资源都按账号隔离，并检查账号模块是否已开通。

账号、机器人、客户

  • module_get、module_update
  • bot_list、bot_get、bot_update
  • account_bot_list、bot_api_key_list
  • customer_list、customer_get
  • customer_tag_list、customer_tag_update、customer_tag_assign
  • account_user_list、account_group_list
  • account_message_list、account_message_search、account_send_message

customer_list 是账号级客户运营列表，支持机器人、关键词、标签和分页筛选；机器人 API 的 list_users 仍保留给旧版 HTTP API 客户端，但不会出现在 MCP 的 tools/list 中。

用户和群运营资源

资源工具遵循统一命名：


<resource>_list

<resource>_get

<resource>_save

<resource>_delete

<resource>_copy

<resource>_run  # 仅支持可执行资源

当前资源包括：

  • 用户：user_reply、user_send、user_sop、user_welcome
  • 群：group_reply、group_send、group_sop、group_join、group_welcome、group_notice、group_broadcast
  • 内容：material、daily_broadcast
  • 监控：sensitive_monitor

例如：user_reply_list、user_reply_save、group_sop_run、material_delete。

AI、会话、归档和任务

以下资源同样使用上述五类资源工具：

  • ai_chat：AI 销冠配置
  • ai_customer：AI 客服配置
  • ai_chat_conversation、ai_customer_conversation
  • ai_chat_task、ai_customer_task
  • ai_chat_record
  • archive
  • job

另外提供：

  • dashboard_get
  • job_list、job_get、job_cancel、job_retry、job_run
  • knowledge_list、knowledge_get、knowledge_create、knowledge_update、knowledge_remove
  • knowledge_batch_update_tags

写操作安全规则

  • 删除类工具建议先传 dry_run=true，确认影响范围后再传 confirm=true。
  • *_run 支持 dry_run=true，执行成功返回 execution_id。
  • 所有 ID 必须属于当前账号，跨账号资源会被拒绝。
  • reg_token、密钥和 API key 不会从工具参数传入，也不会在普通资源返回值中返回。
  • 列表和批量操作有分页或数量限制，避免一次性读取过多数据。
  • 请求会记录请求 ID、工具方法和密钥哈希；不会记录明文密钥。
  • MCP 入口按密钥限制请求频率，超过限制返回 HTTP 429。

机器人 API 兼容说明

机器人 API 密钥和以下 HTTP API 能力继续保留，供历史客户代码使用：list_users、list_groups、消息查询和发送消息。它们不属于 MCP，使用方式和权限规则不变；只有账号级 MCP 密钥可以访问 /mcp。

返回和错误

正常结果以 MCP text content 返回 JSON。写操作返回变更后的资源或执行状态；错误以 MCP isError=true 返回，HTTP 接入错误使用 401、429 或 500。

新增工具必须同步更新本文件，并保证工具名称、参数、权限范围和副作用说明与 tools/list 一致。