开放平台 MCP
开放平台 MCP 让 agent 以你组织的身份读取和分析草料里的数据：查指标、看分布、从数字下钻到具体记录，也能浏览二维码、表单、批量模板、分区这些对象本身。
连接后 agent 会得到 15 个工具，分两类：
- 语义分析工具（7 个）：为分析类问题设计。agent 不需要懂草料的数据结构，从工具返回里就能知道你的组织有哪些业务对象、能算什么指标、每个数字由哪些记录构成。
- 对象浏览工具（8 个）：与 OpenAPI V2 REST 接口对应，回答「这个对象长什么样、有哪些」——活码列表、模板下的子码、组织里的分区等。
注：当前所有工具均为只读，不会改动你组织的任何业务数据。需要写入（添加记录、核销凭证）请使用 OpenAPI V2 REST 接口。
服务信息
| 项 | 值 |
|---|---|
| 服务地址 | https://open.cli.im/mcp |
| 传输方式 | Streamable HTTP |
| 鉴权 | OAuth 授权（内测）或 API Key（Bearer） |
| 能力 | 数据分析 + 对象浏览（只读） |
两种鉴权方式，怎么选
| OAuth 授权 | API Key | |
|---|---|---|
| 适合谁 | 在 WorkBuddy、千问办公等办公 AI 平台里使用的用户 | 开发者、系统集成 |
| 需要准备什么 | 草料账号（内测阶段需先开通白名单） | 在开放平台创建的 API Key |
| 接入动作 | 添加 MCP 后，在弹出的草料授权页登录并确认 | 把 Key 写进客户端配置 |
| 凭证归属 | 你这个用户 + 你授权的组织 | 组织（企业凭证） |
| 取消方式 | 撤销该用户的授权即可 | 需要轮换整个 Key |
注意：开始前先知道两件事：
- OAuth 授权目前处于内测阶段，需要先为你的草料账号开通白名单。请申请，把你的草料账号（登录手机号）发给顾问即可。
- 无论哪种鉴权，授权（或 Key）对应组织的全部数据对 agent 可见，目前不支持只授权某个分区（未使用分区功能的组织可忽略这句）。给他人配置前请确认这一点符合你的预期。
在办公 AI 平台中使用（OAuth 授权）
如果你在腾讯 WorkBuddy、钉钉千问办公这类办公 AI 平台里使用草料数据，按对应平台的图文指南操作：
通用流程都是三步：安装（最快的方式是把下面这段提示词直接发给平台里的 AI，让它自己装）→ 在弹出的草料授权页登录并确认 → 回到平台开始对话。配置里不需要填任何密钥：
帮我安装一个草料二维码的 MCP，具体的 MCP server 配置信息如下：
{
"mcpServers": {
"caoliao": {
"type": "streamable-http",
"url": "https://open.cli.im/mcp",
"timeout": 60
}
}
}如果 AI 回复无法安装，按各平台指南手动添加——粘贴的就是提示词里的那段 JSON 配置。
注：
type用的是 MCP 官方 registry 的传输名streamable-http。这个字段只在你的客户端本地生效、不会发给草料，各家客户端的取值习惯不完全一致（例如 Cursor、VS Code、Claude Code 写http）。如果某个平台提示配置无法识别，改成它自己文档里的写法即可，地址和其余部分不用动。
支持 OAuth 的开发者客户端（如 Claude Desktop 的远程连接器）同样适用：添加 https://open.cli.im/mcp 后按提示完成授权即可，前提是账号已在白名单内。
在开发者客户端中使用（API Key）
这条通道面向开发者和系统集成场景。在办公 AI 平台里使用的用户，请走上面的 OAuth 授权，不需要 API Key。
使用的 API Key 与 鉴权（OpenAPI V2） 中创建的相同。
手动配置
支持 mcpServers JSON 配置的客户端通用：
{
"mcpServers": {
"caoliao": {
"type": "http",
"url": "https://open.cli.im/mcp",
"headers": {
"Authorization": "Bearer <你的API Key>"
}
}
}
}注：连接器名（上例中的
caoliao）由你决定。多数客户端会用它作为工具名前缀，例如caoliao_query_metrics——名字越短，工具列表越清爽。
验证连接
配置完成后重启客户端，工具列表出现草料的 15 个工具即接通。如果列表为空或报 401：
- API Key 方式：检查 Key 是否有效、是否完整（Key 末尾的
=也是内容的一部分） - OAuth 方式：确认已完成授权页流程、账号已开通内测白名单
工具列表
注：这节是给开发者和需要了解细节的人看的。如果你只是在 WorkBuddy、千问办公这类办公 AI 里提问，不需要记住这些工具名——AI 会自己选，直接跳到下一步即可。
语义分析工具（7 个）
回答「多少、占比、分布、趋势」类问题时，agent 一般按 list_metrics → query_metrics → record_list 的顺序走：先了解组织里有什么，再出数，再从数字下钻到具体记录。每个工具的返回都带口径说明和下一步建议，agent 可以自主完成整条链路。
| 工具 | 作用 |
|---|---|
list_metrics | 入口工具。一次返回组织的业务对象目录（表单、分区、码、周期计划）和当前可计算的指标清单 |
get_metric | 查看某个指标的完整定义：统计口径、可用维度、注意事项 |
query_metrics | 按指标出数。支持按表单、分区、码、处理进度、日、月分组，也支持按表单字段的填写值分组和两个维度交叉分组；每个分组结果自带「下钻条件」 |
record_list | 按条件检索记录的行摘要（含还原出的字段名与值）。把 query_metrics 返回的下钻条件原样传入，就能看到构成某个数字的具体记录 |
record_get | 单条记录的完整内容 |
qrcode_get | 单个码的内容 |
form_get | 表单结构：字段名与选项值，是读懂记录数据的钥匙。支持一次传多个表单 ID 批量获取 |
对象浏览工具（8 个）
与 OpenAPI V2 REST 接口对应，字段含义与调用细节见 OpenAPI V2 说明。
| 分类 | 工具 | 作用 |
|---|---|---|
| 活码 | qrcodes_list | 活码列表 |
| 活码 | qrcodes_get_operation | 活码关联操作项 |
| 批量模板 | templates_list | 批量模板列表 |
| 批量模板 | templates_get | 批量模板结构 |
| 批量模板 | templates_list_qrcodes | 模板下子码列表 |
| 批量模板 | templates_get_subcode | 子码内容 |
| 表单 | record_get_form_list | 表单列表 |
| 分区 | projects_list | 分区列表 |
注：早期版本曾提供
qrcodes_get_content、forms_get_template、record_get_record、record_get_records（已分别被qrcode_get、form_get、record_get、record_list取代）以及写入工具record_add_record、certificates_verify。这 6 个工具已从默认工具面移除；如你的既有集成依赖它们，请。
错误码沿用 V2 的同一套，见 错误码说明。
下一步
- 在 WorkBuddy 中使用 —— 办公 AI 平台接入指南
- 鉴权（OpenAPI V2） —— 开发者创建 API Key
- 典型场景 —— 按业务目标看调用组合
- 概览与选型 —— 回看几个入口怎么选