MCP 接入文档

定位

MCP 是面向账号的智能运营能力入口，不属于单个机器人的 API 接入配置。知识库管理以及后续的客户运营、群运营、内容运营和任务执行能力统一在 MCP 中扩展。

所有 MCP 能力复用同一个协议地址，服务端根据 Bearer 密钥识别账号权限或机器人 API 权限，不为不同业务模块增加独立 MCP 地址。

接入信息

后台账号页面提供“MCP 接入”模块。打开后点击“复制给 WorkBuddy”，即可复制包含 MCP 地址、账号级 Bearer 密钥和标准配置 JSON 的完整连接文案。

账号级密钥可以轮换；轮换后旧密钥立即失效，需要重新复制连接文案。


POST https://qw.minapp.xin/mcp

请求使用 Bearer 形式传递密钥：


curl 'https://qw.minapp.xin/mcp' \

  -H 'Authorization: Bearer #{secret}' \

  -H 'Accept: application/json, text/event-stream' \

  -H 'Content-Type: application/json' \

  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

账号级 MCP 密钥和机器人 API 密钥的权限范围相互隔离。调用 tools/list 时，只会返回当前密钥有权使用的工具。

账号级 MCP 可以作为账号范围的 API 管理入口：账号级密钥可以查看当前账号下机器人的 API 密钥及开关状态；机器人 API 的发送、消息查询和会话级权限仍由各机器人后台配置控制。

账号级 MCP 提供通用的账号范围用户和归档消息查询工具。具体业务判断由调用方基于原始消息完成，服务端不预设“未回复”等运营规则。

账号级 MCP

账号级 MCP 密钥绑定账号，不绑定单个机器人或会话。MCP 按业务模块和资源组织工具，而不是把后台 HTTP 路由逐个暴露出来。

账号级 MCP 当前优先提供机器人运营闭环：发现机器人和会话、读取上下文、执行发送。调用方无需进入 Web 界面，也不需要把机器人 API 密钥交给 Codex、WorkBuddy 或其他 MCP harness。

模块级方法

module_get：读取账号模块状态、版本和能力清单。参数：module，当前值为 ai_chat。
module_update：更新模块级状态。参数：module、enabled。对于 ai_chat，该状态控制销冠和客服功能是否可用。

智能体配置

统一使用 agent_type 区分 sales（AI 销冠）和 customer_service（AI 客服）：

agent_list：列出当前账号的智能体配置。参数：agent_type、token_id、active、分页参数。
agent_get：读取一个智能体的完整配置。参数：agent_type、id 或 token_id。
agent_save：创建或更新智能体配置。参数：agent_type、config；服务端按类型校验配置结构。
agent_delete：删除智能体配置。参数：agent_type、id。
agent_copy：复制销冠配置。参数：id；复制后默认停用。
agent_meta：获取行业模板、阶段类型和客服配置可用项。
agent_preview_reply：预览智能体对一条消息的回复。参数：agent_type、id、content、scene_type。

知识库与标签

knowledge_list：查询知识，支持关键词、状态、标签和分页。
knowledge_get：读取知识。
knowledge_create：创建知识。
knowledge_update：更新知识。
knowledge_remove：删除知识。
knowledge_batch_update_tags：批量替换、增加或移除标签。
knowledge_tag_list：列出标签。
knowledge_tag_create：创建标签。
knowledge_tag_update：重命名标签并同步知识。
knowledge_tag_merge：合并标签。
knowledge_tag_delete：删除标签。
knowledge_create_from_messages：从归档消息创建知识。

知识正文最多 50,000 个字符；所有 ID 必须属于当前账号，否则整次操作失败。文件上传不走 MCP JSON 工具，后续以 WorkBuddy 可直接调用的文本参数或独立资源方式提供。

会话、记录与任务

account_bot_list：列出账号下机器人及开放 API、发送、消息查询状态。
account_group_list：列出账号下群会话，可按 token_id 筛选。
account_user_list：列出当前账号下的私聊用户和会话 ID，可按 token_id 筛选。
account_message_list：查询当前账号已归档消息原始列表，可按 token_id、conversation_id、chat_type、since、until 筛选并分页。
account_message_search：在归档消息中按关键词搜索。
account_send_message：通过账号级权限向指定机器人会话发送文本、图片、链接、小程序或名片。
conversation_list：查询销冠会话，支持机器人、阶段、状态、关键词和分页筛选。
conversation_get：读取会话、记忆和任务。
customer_conversation_list：查询客服会话。
customer_conversation_get：读取客服会话详情。
record_list：查询 AI 运行记录。
record_get：读取单条运行记录。
task_list：查询跟进和 AI 任务。
task_cancel：取消待处理任务。
followup_get：读取账号跟进设置。
followup_update：更新账号跟进设置。

仪表盘与归档运营

dashboard_get：获取 AI 模块汇总数据。
archive_bot_list：列出会话归档机器人及状态。
archive_bot_update：更新归档机器人状态。
archive_conversation_list：查询归档会话。
archive_message_list：查询归档消息。
archive_message_send：向归档会话发送人工消息。
material_create_from_message：从归档消息创建素材。

设计约束

1. 所有账号级工具都从 Bearer MCP 密钥解析 reg_token，工具参数不接受 reg_token，避免 WorkBuddy 越权切换账号。

2. 所有资源查询和写入都必须带账号条件；跨账号 ID、机器人 ID 或会话 ID 一律拒绝。

3. agent_type 是稳定的业务枚举，不使用 ai_chat、ai_customer 等数据库集合名暴露给调用方。

4. 返回值统一使用 JSON，写操作返回变更后的资源；列表统一返回 list、total 和 pagination。

5. 删除、发送、取消任务等有副作用的方法保持独立命名，便于 WorkBuddy 做确认和权限控制。

账号级 MCP 可以查看机器人 API 密钥，是为了支持账号级 API 管理；使用账号级密钥时应按账号权限控制其调用范围。

机器人 API MCP

使用机器人开放 API 密钥接入同一个 MCP 地址时，只提供该机器人范围内的 API 工具，并沿用 API 总开关及会话级权限：

list_users：获取用户会话列表。
list_groups：获取群组会话列表。
get_messages：查询指定会话的归档消息。
send_message：向指定会话发送消息。

HTTP API 的具体字段、消息格式和权限规则参见 API 接口文档。

工具规划

MCP 工具按业务域命名和扩展。除现有账号与知识库工具外，后续运营能力将继续归入本模块，例如客户运营、群运营、内容管理、标签管理和任务执行。新增工具应继续使用账号级权限，并在本文件维护方法、参数和返回值说明。

MCP 文档