首页文档OctoHz MCPOctoHz MCP 使用教程

OctoHz MCP 使用教程

OctoHz 提供了一个远程 MCP（Model Context Protocol）server，让 Claude、Codex 等任何兼容 MCP 的智能体客户端可以直接读写项目归档、待办、密码库/主机/API 密钥、公开文档、私有文档、站内内容的发现与发布、导航书签、私人与站内公共资源库，以及八字/风水/经文/咒语/股票/饭店/食谱这类个人数据，不需要单独装 CLI 或自己写 HTTP 客户端代码。除了需要读本地仓库文件的 sync，CLI 的所有命令组在 MCP 里都有对应。

Endpoint

https://octohz.com/api/mcp

协议：MCP Streamable HTTP（stateless 模式，服务端不维护 session，每次请求独立处理）
只支持 POST（JSON-RPC 2.0）；GET/DELETE 会返回 405
鉴权：Authorization: Bearer <apiToken>——跟 CLI 用的是同一个 token，在账号设置页生成

不带 token 也能调用公开工具（如 doc_get、search_content、category_list、site_resource_list），但涉及个人数据或写操作的工具必须带 token，否则返回 isError: true，提示"未授权"。

密码库 / 主机 / API 密钥这三类走的是另一套鉴权：独立的、限次读取的 privateKey（账号设置页单独生成，跟 apiToken 不是一回事）。这套 key 不放在 Authorization header，而是作为每个 vault tool 自己的参数传——因为一次 MCP 连接的 header 是固定的，没法按 tool 切换成两种不同的 token，做成参数就能每次调用显式指定。list 类 tool 免费不耗额度，单条读取（如 password_get）消耗 1 次额度，额度耗尽后该 key 自动失效，需要去账号设置页重新生成。vest_publish 的 vestToken（马甲身份）也是同样的理由，同样走参数。

接入方式

Claude Code

claude mcp add --transport http octohz https://octohz.com/api/mcp \
  --header "Authorization: Bearer <your-apiToken>"

Codex（桌面版 / CLI）

Codex 的技能（skill）只提供使用说明，不会自动注册 MCP。远程 MCP 要单独写入用户级 ~/.codex/config.toml；官方推荐用 CLI 注册，CLI 与 Codex 桌面版共用这份配置：

codex mcp add octohz `
  --url https://octohz.com/api/mcp `
  --bearer-token-env-var OCTOHZ_API_TOKEN

codex mcp list
codex mcp get octohz

注册后完全退出并重新打开 Codex，再新建任务；已经运行的桌面进程和旧任务不会自动获得新 MCP 工具。设置页“插件 → MCP”中应能看到 octohz。

Windows 上更安全的认证方式

bearer_token_env_var 是标准配置，但本地智能体启动的 shell 子进程也可能继承该环境变量。已经使用 OctoHz CLI 的 Windows 用户，可以改用 Codex 的 http_headers_helper，让 MCP 客户端调用时才从现有 CLI 配置读取 token，避免把 token 放进任务环境。

例如新建 %USERPROFILE%\.octohz\mcp-headers.ps1：

$config = Get-Content -Raw "$env:USERPROFILE\.octohz\config.json" | ConvertFrom-Json
if ([string]::IsNullOrWhiteSpace([string]$config.token)) {
  throw "OctoHz token is not configured"
}
@{ Authorization = "Bearer $($config.token)" } | ConvertTo-Json -Compress

然后在 ~/.codex/config.toml 中配置，并把示例里的 your-name 换成实际 Windows 用户目录名：

[mcp_servers.octohz]
url = "https://octohz.com/api/mcp"
http_headers_helper = 'powershell.exe -NoProfile -ExecutionPolicy Bypass -File "C:\Users\your-name\.octohz\mcp-headers.ps1"'

不要把真实 token 直接写进教程、项目文件、命令历史或可被智能体读取的日志。非交互模式若使用 approval_policy=never，需要审批的 MCP 调用会被拒绝；这是客户端审批策略，不是连接失败。

136 个 Tool 会不会占满上下文

支持 Tool Search 的新版本 Codex 会把 MCP 工具延迟加载：任务启动时只保留很小的发现入口，需要调用时才按需载入匹配工具的 schema，不会把 136 个完整 schema 全部塞进每一轮上下文。

2026-09-23 在 Codex CLI 0.155.0-alpha.16 上做过一组同提示、全新进程的对照测试：

状态	首轮 input tokens
启用 OctoHz MCP	15,769
临时禁用 OctoHz MCP	15,763

启动差异只有 6 tokens；随后要求读取公开文档 84 时，事件流才选择 octohz/doc_get。这说明该版本没有在新任务启动时全量加载 136 个 schema。不同客户端、模型和版本的实现可能不同；不支持 Tool Search 的客户端仍可能急加载全部工具，可用 enabled_tools 白名单限制暴露范围。

通用 MCP client 配置

大多数支持远程 MCP（HTTP transport）的客户端配置格式类似：

{
  "mcpServers": {
    "octohz": {
      "url": "https://octohz.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-apiToken>"
      }
    }
  }
}

具体字段名以各家客户端文档为准（有的叫 url，有的叫 serverUrl）。注意只有支持 HTTP/Streamable HTTP transport 的客户端能连——纯 stdio 型 MCP 客户端连不了远程 server。

可用 Tool（共 149 个）

验证于 2026-09-26，server 2.11.0。数字以 tools/list 实时结果为准，本节由 tools/mcp/doc-tools-table.ts 生成。

鉴权速查：标题标注 apiToken 的分类需要 Authorization: Bearer <apiToken>；privateKey 作为工具参数传入；“公开读取”无需鉴权；“管理员写入”除 apiToken 外还要求管理员权限。表内仅保留例外权限，避免每行重复。

项目归档（apiToken）

写入类工具（决策、坑、任务、交接事件的新增与修改）都可以选传 actor，记录“是谁写的”（和 CLI 的 --actor 一致）；不传时新增类记 mcp、修改类记 agent。

Tool	说明	必填参数
`project_list`	列出我的项目归档（摘要字段）。	无
`project_get`	读取 OctoHz 我的项目归档。默认返回摘要索引（各段 summary + 子资源 url）；full=true 返回完整数据；section 指定时只返回该段（definition/status/ops/decisions/pitfalls/design/data_models）。	`id`（另有 2 个可选）
`project_onboard`	一次调用拿到安全上手所需的最小集：definition + onboarding + active 决策 + active 坑 + 开放任务 + 最近事件 + 各段新鲜度。新智能体接手项目永远从这个 tool 开始。	`id`（另有 1 个可选）
`project_events`	读取项目交接事件时间线，最近的在前。	`id`（另有 1 个可选）
`project_list_entries`	列出项目归档下的条目（decision/pitfall/task/event/note），可按 kind/status 过滤。	`id`（另有 2 个可选）
`project_entry_get`	按编号（D001/P001/T001/E001/N001）或数字 id 读取一条条目的完整内容。	`id`、`ref`
`project_add`	创建一个新的项目归档，entries 聚合自创建起即生效。对应 CLI 的 `octohz project add`。	`name`（另有 2 个可选）
`project_patch`	智能合并更新 definition/ops/design 文档段：对象深合并，已知数组按 key upsert（env_vars→key, servers→address 等），字段传 null 删除。decision/pitfall/task/event 请用对应的专门 tool。对应 CLI 的 `octohz project patch`。	`id`（另有 6 个可选）
`project_decision_add`	记录一条决策，服务端分配 D 编号。对应 CLI 的 `octohz project decision add`。	`id`、`title`、`decision`（另有 3 个可选）
`project_decision_edit`	按编号（如 D003）更新决策字段，只传的字段会改；supersede=true 标记为已废弃。对应 CLI 的 `octohz project decision edit`。	`id`、`ref`（另有 6 个可选）
`project_pitfall_add`	记录一个坑，服务端分配 P 编号。对应 CLI 的 `octohz project pitfall add`。	`id`、`title`、`severity`、`condition`、`consequence`、`solution`（另有 1 个可选）
`project_pitfall_edit`	按编号（如 P003）更新坑的字段，只传的字段会改。对应 CLI 的 `octohz project pitfall edit`。	`id`、`ref`（另有 6 个可选）
`project_pitfall_resolve`	按编号把一个坑标记为已解决。对应 CLI 的 `octohz project pitfall resolve`。	`id`、`ref`
`project_task_list`	列出开放任务（pending + in_progress），含认领人；all=true 包含已完成。	`id`（另有 1 个可选）
`project_task_add`	新增一个待认领任务，服务端分配 T 编号，默认 status=pending。对应 CLI 的 `octohz project task add`。	`id`、`title`（另有 2 个可选）
`project_task_claim`	认领一个任务（置 in_progress + 记认领人），防止多智能体重复做同一件事。对应 CLI 的 `octohz project task claim`。	`id`、`ref`（另有 1 个可选）
`project_task_done`	把任务标记为 done，并自动追加一条完成事件到时间线。对应 CLI 的 `octohz project task done`。	`id`、`ref`（另有 1 个可选）
`project_log_event`	给项目归档新增一条 event 条目（交接记录），服务端自动分配编号并写快照。对应 CLI 的 `octohz project log`。	`id`、`title`（另有 6 个可选）
`project_entry_rm`	按编号（如 N001）或数字 id 删除一条条目。对应 CLI 的 `octohz project entry-rm`。	`id`、`ref`
`project_snapshot_list`	列出项目的版本快照（不含内容，只有 id/note/时间）。	`id`
`project_snapshot_get`	读取某个版本快照的完整内容。	`id`、`sid`
`project_snapshot_restore`	把文档段（definition/ops/design，迁移后的项目条目不受影响）恢复到某个历史快照；恢复前会自动备份当前版本。	`id`、`sid`
`project_migrate_entries`	把 2026-08-17 之前创建、从未迁移过的老项目的旧 JSONB 列（decisions/pitfalls/status）迁移为条目。新项目创建时已自动激活，此 tool 对新项目会报 already_migrated。dry=true 只预览不写入；即使 counts 全 0 也建议正式执行一次以激活聚合。	`id`（另有 1 个可选）

密码库（需要 privateKey）

Tool	说明	必填参数
`password_list`	列出密码条目（不含密码字段，免费不耗额度）。	`privateKey`
`password_get`	按 id 读取一条密码的完整明文，消耗 1 次 privateKey 额度。	`privateKey`、`id`
`password_add`	新增一条密码记录（加密存储）。	`privateKey`、`title`、`password`（另有 4 个可选）
`password_update`	整条覆盖更新一条密码记录（title/password 必填，与 CLI 行为一致，非局部 patch）。	`privateKey`、`id`、`title`、`password`（另有 4 个可选）
`password_rm`	删除一条密码记录。	`privateKey`、`id`

主机（需要 privateKey）

Tool	说明	必填参数
`host_list`	列出主机（不含 rootPassword/panelPassword，免费不耗额度）。	`privateKey`
`host_get`	按 id 读取一台主机的完整凭据（root/面板密码），消耗 1 次 privateKey 额度。	`privateKey`、`id`
`host_find`	按公网/内网 IP 查找主机：精确匹配优先，无精确匹配再回退到包含匹配。默认免费只列匹配项（不含密码）；reveal=true 且唯一匹配时才读取完整凭据（消耗 1 次额度）。	`privateKey`、`ip`（另有 1 个可选）
`host_add`	新增一台主机记录（密码字段加密存储）。	`privateKey`、`name`（另有 17 个可选）
`host_update`	局部更新主机字段：只传的字段会改，其余保持不变。	`privateKey`、`id`（另有 18 个可选）
`host_rm`	删除一台主机记录。	`privateKey`、`id`

我的 API（需要 privateKey）

Tool	说明	必填参数
`api_list`	列出第三方 API/服务订阅条目（不含 apiKey 字段，免费不耗额度）。	`privateKey`
`api_get`	按 id 读取一条 API 服务的完整密钥，消耗 1 次 privateKey 额度。	`privateKey`、`id`
`api_add`	新增一条第三方 API/服务订阅记录（apiKey 加密存储）。	`privateKey`、`name`、`apiKey`（另有 6 个可选）
`api_update`	局部更新一条 API 记录：只传的字段会改。	`privateKey`、`id`（另有 8 个可选）
`api_rm`	删除一条 API 记录。	`privateKey`、`id`

内容发现与发布（混合鉴权）

Tool	说明	必填参数
`util_get_title`	抓取一个 URL，提取	`url`
`category_list`	列出发布内容可用的分类（id/name/slug），发布前先查一下，submit_post 的 category 参数直接用这里的 id 或 slug。	无
`search_content`	跨类型全文搜索：帖子/论坛/文档/推荐集/资源。不带 token 时搜索公开内容；带 apiToken 时也能搜索仅会员可见的内容。	`q`（另有 3 个可选）
`product_get`	读取一篇内容详情（含正文）。仅会员可见的内容需要 apiToken 才能读到。	`id`
`product_list`	按条件列出已发布内容（分类/发布者/关键词/日期/排序等）。带 apiToken 时也能看到仅会员可见内容。	均可选
`product_patch`	局部更新一篇内容（只更新传入字段），本人或 admin 可操作。封面图传 imageUrl（服务端抓取）或 imageBase64（+可选 imageMimeType）二选一。	`id`（另有 10 个可选）
`submit_post`	发布一条新内容（推荐/资源等）。category 可传数字 id 或 slug/名称（先用 category_list 查可用值）。封面图传 imageUrl（服务端抓取）或 imageBase64（+可选 imageMimeType）二选一，都不传则无封面图。	`name`、`intro`、`category`（另有 7 个可选）
`essay_post`	发一条 essay 类型的短内容（≤100 字，类似推文）。	`content`
`product_delete`	彻底删除一篇内容（级联清理评论/点赞/收藏/tag/合集条目/举报）。仅管理员可操作——发布者本人也无权限，这是站点现有权限模型（后台管理页同款），不可撤销。	`id`
`vest_publish`	用马甲（vest）身份发布一条内容，跟 submit_post 用 apiToken 发布是同一套发布逻辑，区别是归属和展示身份是马甲而不是本人。vestToken 在 octohz.com/my/vests 获取，作为参数传（不是 Authorization header，理由同 privateKey）。封面图传 `imageUrl`（服务端抓取）或 `imageBase64`（+可选 `imageMimeType`）二选一，都不传则无封面图。	`vestToken`、`name`、`intro`、`category`（另有 6 个可选）

公开文档（公开读取 / 管理员写入）

Tool	说明	必填参数
`doc_get`	读取 OctoHz 公开文档（/docs 板块，对应 tutorial 表），公开内容。	`id`
`doc_list`	列出公开文档（/docs 板块），公开内容。	均可选
`doc_category_list`	列出 /docs 板块的分类（id/name），doc_add 的 categoryId 参数对照用。	无
`doc_category_add`	新建一个公开文档（/docs 板块）分类，可选挂在父分类下。仅管理员可操作。	`name`（另有 3 个可选）
`doc_add`	新建一篇公开文档（/docs 板块）。仅管理员可操作。	`title`、`content`（另有 4 个可选）
`doc_update`	整体覆盖更新一篇公开文档——title/content 都是必填，会替换全文。建议先 doc_get 读出当前内容再改，避免误删正文。仅管理员可操作。	`id`、`title`、`content`（另有 4 个可选）
`doc_delete`	删除一篇公开文档，不可撤销。仅管理员可操作。	`id`

我的文档（公开分享免鉴权 / 其余 apiToken）

Tool	说明	必填参数
`private_doc_list`	列出我的私有文档（笔记），可按文件夹过滤。	均可选
`private_doc_get`	读取一篇私有文档的完整内容；本人可用 apiToken 读取，isPublic=true 时任何人均可免鉴权读取。	`id`
`private_doc_add`	新建一篇私有文档（笔记），可选新建时直接置顶 / 公开。	`title`（另有 4 个可选）
`private_doc_update`	局部更新一篇私有文档，只传的字段会改；categoryId 传 null 清除文件夹。	`id`（另有 5 个可选）
`private_doc_rm`	删除一篇私有文档，不可撤销。	`id`
`private_doc_category_list`	列出我的私有文档文件夹（可嵌套，parentId 指向父文件夹）。	无
`private_doc_category_add`	新增一个私有文档文件夹，可选挂在某个父文件夹下。	`name`（另有 1 个可选）
`private_doc_category_patch`	改名或切换公开状态，只传的字段会改。	`id`（另有 2 个可选）
`private_doc_category_rm`	删除一个私有文档文件夹；旗下文档的文件夹会被置空，不会被删除。	`id`

待办（apiToken）

Tool	说明	必填参数
`todo_list`	列出我的待办事项。	无
`todo_create`	新建一条待办事项。	`content`
`todo_complete`	把一条待办标记为已完成（或取消完成）。	`id`（另有 1 个可选）
`todo_update`	改一条待办的内容或置顶状态，只传的字段会改。	`id`（另有 2 个可选）
`todo_rm`	删除一条待办事项。	`id`

导航书签（apiToken）

Tool	说明	必填参数
`nav_list`	列出我的导航书签。	无
`nav_add`	新增一条导航书签。	`title`、`url`（另有 3 个可选）
`nav_patch`	局部更新一条导航书签，只传的字段会改。	`id`（另有 6 个可选）
`nav_rm`	删除一条导航书签。	`id`
`nav_category_list`	列出我的导航书签分类。	无
`nav_category_add`	新增一个导航书签分类。	`name`
`nav_category_rename`	重命名一个导航书签分类。	`id`、`name`
`nav_category_rm`	删除一个导航书签分类；旗下书签的分类会被置空，不会被删除。	`id`

站内公共资源库（公开读取 / apiToken 写入）

Tool	说明	必填参数
`site_resource_category_list`	列出官方资源库分类，含每类资源数。	无
`site_resource_category_add`	新增一个官方资源库分类。仅管理员可操作。	`name`（另有 2 个可选）
`site_resource_category_patch`	改名/置顶/排序一个官方资源库分类，只传的字段会改。仅管理员可操作。	`id`（另有 3 个可选）
`site_resource_category_rm`	删除一个官方资源库分类。仅管理员可操作。	`id`
`site_resource_list`	列出官方资源库条目，可按分类过滤。	均可选
`site_resource_get`	读取一条官方资源的完整信息（含版本历史）。	`id`
`site_resource_add`	新增一条官方资源，自动创建初始版本记录。fileUrl 让服务端抓取资源文件（≤50MB，30s 超时，不限格式）；iconUrl/iconBase64 设置封面图标。仅管理员可操作。	`title`、`summary`（另有 8 个可选）
`site_resource_patch`	更新一条官方资源的标题/摘要/说明/分类/图标/置顶/排序，只传的字段会改。管理员或发布人本人可操作。不改版本或文件，改文件用 site_resource_publish_version。清空图标传 `removeIcon=true`（或 `iconUrl` 传空字符串）。	`id`（另有 11 个可选）
`site_resource_publish_version`	给一条官方资源追加一个新版本记录，并更新资源当前版本号/文件。fileUrl 不传则沿用上一版本的文件。管理员或发布人本人可操作。	`id`、`version`（另有 3 个可选）
`site_resource_downloads`	列出一条官方资源的下载记录。管理员或发布人本人可查看。	`id`
`site_resource_rm`	删除一条官方资源及其版本历史。仅管理员可操作。	`id`

私人资源库（apiToken）

Tool	说明	必填参数
`resource_category_list`	列出我的资源库分类，含每类资源数。	无
`resource_category_add`	新增一个资源库分类。	`name`
`resource_category_rename`	重命名一个资源库分类。	`id`、`name`
`resource_category_patch`	改名/置顶/排序一个我的资源库分类，只传的字段会改（同 site_resource_category_patch，但作用于私人资源库）。	`id`（另有 3 个可选）
`resource_category_rm`	删除一个资源库分类。	`id`
`resource_list`	列出我的资源库条目，可按分类过滤。	均可选
`resource_get`	读取一条资源的完整信息（含版本历史）。	`id`
`resource_add`	新增一条资源，自动创建初始版本记录。fileUrl 让服务端抓取资源文件（≤50MB，30s 超时，不限格式）；iconUrl/iconBase64 设置封面图标，规则同 submit_post。	`title`、`summary`（另有 8 个可选）
`resource_patch`	更新一条资源的标题/摘要/说明/分类/图标/分享开关/置顶/排序，只传的字段会改。不改版本或文件，改文件用 resource_publish_version。清空图标传 `removeIcon=true`（或 `iconUrl` 传空字符串）。	`id`（另有 12 个可选）
`resource_publish_version`	给一条资源追加一个新版本记录，并更新资源当前版本号/文件。fileUrl 不传则沿用上一版本的文件。	`id`、`version`（另有 3 个可选）
`resource_downloads`	列出一条资源的下载记录。	`id`
`resource_rm`	删除一条资源及其版本历史。	`id`

八字（我的命理，apiToken）

Tool	说明	必填参数
`bazi_list`	列出我的八字记录（摘要，含日主/五行/调候/刑冲合害）。	无
`bazi_get`	读取一条八字记录的完整排盘（四柱/大运/流年/神煞）。	`id`
`bazi_add`	新增一条八字排盘记录。	`name`、`gender`、`year`、`month`、`day`（另有 4 个可选）
`bazi_patch`	局部更新一条八字记录，只传的字段会改。	`id`（另有 10 个可选）
`bazi_rm`	删除一条八字记录。	`id`

风水（我的房屋，apiToken）

Tool	说明	必填参数
`fengshui_list`	列出我的房屋风水记录（摘要）。	无
`fengshui_get`	读取一条房屋风水记录的完整排盘（八宅九宫/玄空飞星/装修数据），每次实时用当前算法重算。	`id`
`fengshui_add`	新增一条房屋风水记录，服务端计算三元九运/命卦/八宅九宫/玄空飞星。	`name`、`facingDegree`、`moveInYear`、`birthDate`、`gender`（另有 1 个可选）
`fengshui_patch`	局部更新一条风水记录；facingDegree/moveInYear/birthDate/gender 任一变化都会整体重新计算。	`id`（另有 7 个可选）
`fengshui_rm`	删除一条房屋风水记录。	`id`

经文库（apiToken）

Tool	说明	必填参数
`sutra_list`	列出我的经文库。	无
`sutra_get`	读取一条经文的完整内容。	`id`
`sutra_add`	新增一条经文记录。	`name`（另有 6 个可选）
`sutra_patch`	局部更新一条经文，只传的字段会改。	`id`（另有 7 个可选）
`sutra_rm`	删除一条经文记录。	`id`

咒语库（apiToken）

Tool	说明	必填参数
`zhouyu_list`	列出我的咒语库。	无
`zhouyu_get`	读取一条咒语的完整内容。	`id`
`zhouyu_add`	新增一条咒语记录。	`name`（另有 6 个可选）
`zhouyu_patch`	局部更新一条咒语，只传的字段会改。	`id`（另有 7 个可选）
`zhouyu_rm`	删除一条咒语记录。	`id`

股票（apiToken）

Tool	说明	必填参数
`stock_list`	列出我的股票持仓。	无
`stock_search`	按名称/代码搜索股票，返回 symbol（Yahoo Finance 格式）和实时价格，供 stock_add 使用。整合腾讯/东方财富/Yahoo Finance 数据源。	`q`
`stock_add`	新增一条股票持仓；code 用 stock_search 返回的 symbol（Yahoo Finance 格式，如 600519.SS/AAPL）。	`name`、`code`、`market`、`buyPrice`、`currentPrice`（另有 1 个可选）
`stock_refresh`	批量刷新持仓的当前价格（腾讯行情）。	均可选
`stock_patch`	局部更新一条持仓（价格/数量/名称等），只传的字段会改。	`id`（另有 6 个可选）
`stock_rm`	删除一条股票持仓记录。	`id`

我的饭店（apiToken）

Tool	说明	必填参数
`restaurant_list`	列出我的饭店笔记，可按分类过滤。	均可选
`restaurant_get`	读取一条饭店笔记。	`id`
`restaurant_add`	新增一条饭店笔记。	`name`（另有 5 个可选）
`restaurant_patch`	局部更新一条饭店笔记，只传的字段会改。	`id`（另有 6 个可选）
`restaurant_rm`	删除一条饭店笔记。	`id`

我的食谱（apiToken）

Tool	说明	必填参数
`recipe_list`	列出我的食谱，可按分类过滤。	均可选
`recipe_get`	读取一条食谱。	`id`
`recipe_add`	新增一条食谱。	`name`（另有 5 个可选）
`recipe_patch`	局部更新一条食谱，只传的字段会改。	`id`（另有 6 个可选）
`recipe_rm`	删除一条食谱。	`id`

工作台（AI 生成，会扣余额）

工作台（/my/console）的 AI 功能，每次调用都按实际消耗从余额扣费，提交即扣、不可撤销，调用前可先用 console_balance 查余额。生成类是异步的：*_submit 提交后返回任务标识，再用对应的 *_status 每 5~10 秒轮询一次。MCP 传不了本地文件，素材只能传公网 URL；要上传视频/图片文件（提取口播、视频详情、本地图片作参考）请用 octohz CLI。

console_product_video_submit 支持 3 个模型 × 3 种模式，mode 必填：

模型	时长	分辨率
`h3`（MiniMax H3，默认）	5~15 秒	480P / 768P / 2K / 4K
`seedance2`（Seedance 2.0）	4~15 秒	480p / 720p / 1080p
`seedance25`（Seedance 2.5）	4~30 秒	480p / 720p

mode：text 文生视频（只有提示词）；image 图生视频（imageUrl 首帧，可选 endImageUrl 尾帧）；reference 参考生视频（imageUrls/videoUrls/audioUrls 只作参考，至少要有 1 张图或 1 段视频，音频不能单独用）。提示词里引用参考图：H3 写 Image 1，Seedance 写 @Image1。时长或分辨率超出所选模型的范围会直接返回错误，不会自动改成默认值。

Tool	说明	必填参数
`console_balance`	查看工作台余额和今日消耗（元）。	无
`console_meta_prompt`	把视频分析报告转成分镜/视频生成提示词，按消耗扣费，不带参考图。	`report`、`videoModel`（另有 2 个可选）
`console_history`	列出口播 / 视频详情 / 元提示词的历史任务，每页 5 条。	`kind`（另有 1 个可选）
`console_history_rm`	删除口播 / 视频详情 / 元提示词的一条历史记录（只能删自己的，不可恢复）。	`kind`、`id`
`console_product_video_submit`	提交生视频任务（H3 / Seedance 2.0 / 2.5 × 文生 / 图生 / 参考生），提交即扣费。	`prompt`、`mode`（另有 11 个可选）
`console_product_video_status`	轮询带货视频任务，COMPLETED 时返回视频地址。	`statusUrl`、`resultUrl`
`console_local_image_submit`	提交本地（3090X2）文生图任务，仅管理员。可选社区工作流、一致性角色、多样性 LoRA，须与模型搭配（角色/`sda` 只配 `z-image-turbo`，`workflow` 只配 `krea2-moody-v8`），不匹配在扣费前报错；图片编辑要传本地图，只能用 CLI。	`prompt`（另有 7 个可选）
`console_local_image_status`	轮询本地生图任务，COMPLETED 时返回图片地址，仅管理员。	`promptId`、`outputNodeId`
`console_local_video_submit`	提交本地（3090X2）视频任务，仅管理员；MCP 只支持无需图片的模式（h3 纯文本，走 fl2va 权重；ltx25 的 t2v / hd），可选社区概念 LoRA（`communityLora`，须与模型家族对得上）；H3 的首帧/尾帧（fl2va）与参考图（ref2va）、Wan2.2 系、一致性角色都要传本地图片，只能用 CLI。	`model`、`prompt`、`durationSec`（另有 2 个可选）
`console_local_video_status`	轮询本地生视频任务，COMPLETED 时返回视频地址，仅管理员。	`promptId`、`outputNodeId`

智能互通（查看其他智能体，apiToken）

只读：列出你在智能互通网络里能联系的智能体，权限范围和 /api/agent-hub/discover 一致（自己的 + 被授权的，只看 active）。不发消息、不改授权；发消息要走本机 Bridge 的 127.0.0.1:9911，远程 MCP 够不到，请用 octohz CLI / Agent Bridge。能力列表是对方自行声明的展示信息，不参与授权。

Tool	说明	必填参数
`agent_list`	列出可联系的智能体（agent_id、名称、类型、是否在线、能否访问、开放的操作范围），默认不带能力列表。	均可选（`onlineOnly`、`withCapabilities`）
`agent_get`	按 agent_id 看一个智能体的完整信息：连接方式、Agent Card 地址、开放给你的操作范围。不含密钥。	`agentId`

调用示例

下面先给出一个完整请求模板。替换 name 和 arguments 即可调用其他工具；公开工具或只使用 privateKey 的工具可以省略 Authorization header。

curl -s -X POST https://octohz.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer <your-apiToken>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "project_onboard", "arguments": { "id": 1, "brief": true } }
  }'

常用 `params`

接手项目：

{ "name": "project_onboard", "arguments": { "id": 1, "brief": true } }

认领任务并在完成后写入交接记录：

{ "name": "project_task_claim", "arguments": { "id": 1, "ref": "T003", "owner": "my-agent" } }
{ "name": "project_task_done", "arguments": { "id": 1, "ref": "T003", "note": "接入了七牛云 CDN 并验证" } }

按 IP 查找主机凭据（privateKey 是参数，不是 Authorization header）：

{ "name": "host_find", "arguments": { "privateKey": "<your-privateKey>", "ip": "192.168.1.50", "reveal": true } }

发布带封面的内容；先用 category_list 查询分类：

{
  "name": "submit_post",
  "arguments": {
    "name": "标题",
    "intro": "一句话简介",
    "description": "正文，支持 Markdown",
    "category": "software",
    "buyText": "https://example.com",
    "imageUrl": "https://example.com/cover.png"
  }
}

读取完整八字排盘：

{ "name": "bazi_get", "arguments": { "id": 1 } }

新增资源并让服务端抓取文件：

{
  "name": "resource_add",
  "arguments": {
    "title": "标题",
    "summary": "一句话摘要",
    "fileUrl": "https://example.com/package.zip"
  }
}

返回格式

所有 tool 都返回标准 MCP content 数组，正文是 JSON.stringify 后的字符串；失败时 isError: true，content[0].text 是可读的中文错误说明（未授权 / 不存在 / 校验失败 / 额度用完等）。

下一步

我的项目 API —— REST 接口细节，MCP tool 底层调用的就是这套逻辑
OctoHz CLI 快速上手 —— 包含依赖本地仓库文件的 sync 工作流
OctoHz 智能体使用指南 —— Agent 接入总览

OctoHz MCP 使用教程

OctoHz MCP 使用教程

Endpoint

接入方式

Claude Code

Codex（桌面版 / CLI）

Windows 上更安全的认证方式

136 个 Tool 会不会占满上下文

通用 MCP client 配置

可用 Tool（共 149 个）

项目归档（apiToken）

密码库（需要 privateKey）

主机（需要 privateKey）

我的 API（需要 privateKey）

内容发现与发布（混合鉴权）

公开文档（公开读取 / 管理员写入）

我的文档（公开分享免鉴权 / 其余 apiToken）

待办（apiToken）

导航书签（apiToken）

站内公共资源库（公开读取 / apiToken 写入）

私人资源库（apiToken）

八字（我的命理，apiToken）

风水（我的房屋，apiToken）

经文库（apiToken）

咒语库（apiToken）

股票（apiToken）

我的饭店（apiToken）

我的食谱（apiToken）

工作台（AI 生成，会扣余额）

智能互通（查看其他智能体，apiToken）

调用示例

常用 params

返回格式

下一步

常用 `params`