执行前先查操作开放范围与兼容性。
hbd --help --json 里列出了 hbd mcp serve 的版本,可以把自己的命令交给同一台电脑上的智能体客户端,例如 Claude Code 或 Codex。客户端自己启动 hbd mcp serve --stdio,通过标准输入和标准输出与它通信,所以没有要连接的服务地址。Humanbased 不运行托管的 MCP 服务。
| 作用 | 命令 | 所需权限 |
|---|---|---|
| 把这个版本的命令提供给本机的智能体客户端 | hbd mcp serve --stdio | — |
每条命令对应一个工具,工具名就是命令名,空格换成下划线:campaign_list 运行 hbd campaign list,campaign_versions_inspect 运行 hbd campaign version show。工具的参数就是这条命令自己的参数,名字不变,例如 campaign-id、limit、idempotency-key;返回的是 --json 打印的同一个信封。只有命令成功时,其中的 error 才是 null。
需要人亲自完成的命令不提供:登录和退出登录、撤销会话、执行已确认的发布。
接入客户端
每次调用使用的凭证,和你在终端运行同一条命令时一样:服务进程的环境里设了 HB_API_KEY 就用它,否则用 hbd auth login 为服务所用 profile 保存的会话。启动 hbd mcp serve 时给的 --profile 和 --timeout 对每次调用都生效。
Claude Code:
claude mcp add --transport stdio humanbased -- humanbased mcp serve --stdio
claude mcp get humanbasedCodex,写在 ~/.codex/config.toml:
[mcp_servers.humanbased]
command = "humanbased"
args = ["mcp", "serve", "--stdio"]
default_tools_approval_mode = "writes"确认会改动什么
标为只读的工具不改动服务器上的任何东西。其余工具会改动活动Developer 组织的一组数据工作及其相关设置、发布提案、模板、提交的结论、Academy 课程草稿或对贡献者答案的打分、上传的文件,或本机的 profile。对它们的每次调用,Claude Code 都会先问你,即使它的权限模式原本会直接放行;Academy 课程命令、files upload 和 campaign input import 除外。智能体可以不问你就编写课程草稿、提交审核、给开放题打分、上传图片,或把本组织的数据集导入活动(经 MCP 只能导入草稿或暂停中的活动,运行中的活动由人在终端导入),所以对这几个命令,Claude Code 只在它自己的权限设置要求时才先问。设了 default_tools_approval_mode = "writes" 时,Codex 会在每个没标只读的工具运行前询问,这几个也一样。
已保存的 CLI 会话在登录时批准的组织内写入,无需再传 --org。使用 API Key 时,启动服务要加 --org <组织 id>、设置 HB_ORG,或在每次写操作中传 org。显式指定的组织与凭证不符时,写操作以 ORG_MISMATCH 被拒绝,请求不会发出。
文件、路径与等待
通过 MCP 运行时,campaign init、template init 和 campaign plan 不写文件:本该写出的文档放在 data.artifact 里返回。把它保存到你想要的位置,再把路径作为 file 传给 campaign validate,或作为 plan 传给 campaign apply。其他命令的 --out 原本会写出的内容,已经在 data 里。
标准输入用来传协议,所以文件参数写 - 会被拒绝,要给路径。相对路径从客户端启动服务时所在的目录算起。
通过 MCP 运行时,files upload 只收图片(PNG、JPEG、WebP、GIF、HEIC、HEIF、AVIF、TIFF 或 BMP),按文件开头的字节判断,不看文件名。其他文件在读其余部分、发出任何请求之前就会被拒绝。以 campaign 或 cover 类别上传的文件是公开的,拿到地址的人都能读。
campaign records pull 每次调用返回一页,内容就是命令自己输出的 JSON 文本,记录里的数字一位不差。读下一页时,把 data.next_cursor 作为 cursor、data.subscription_id 作为 subscription 传回去。要一次导出全部记录,在终端运行这条命令并加 --all。
服务一次只处理一个调用。任何调用等待服务端任务都不超过 45 秒,所以能在 Codex 默认给工具调用的 60 秒内返回(可用 tool_timeout_sec 调大)。
dsa_consult 在 DSA 受理问题后立即返回,运行 ID 在 data.run_id 里。之后用带 wait 的 dsa_run 跟进这次运行,每次最多跟进 45 秒。到时运行还没结束的话,返回的不是错误:data.status 是 queued 或 running,data.cursor 标出看到了哪里,附注里写明下一次调用,即把 after 设为 data.cursor 再调 dsa_run。带 wait 的 campaign_apply 到 45 秒时返回的是 WAIT_TIMEOUT:应用仍在进行,并没有失败;再调用一次就能继续跟进。
客户端取消调用时,正在读取或等待的调用立即停止。已经发出的写请求会执行完,因为它可能已经生效;之后不再发送任何请求。如果这次写操作带了 idempotency-key,用同一个键再发一次就能读回它的结果,不会重复执行。
客户端结束会话时,服务用同样的方式停下手上的调用,然后退出;还在排队的调用不会开始。