社区 MCP 访问指南

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-13 ｜ 来源：chenghub/src/mcp、chenghub/src/mcp/tools、chenghub/src/services/doc_service.rs、chenghub/web/src/features/account/McpConfigPanel.tsx、chenghub/config/default.toml

ChengHub 本身就是一个 MCP 服务器。把任何支持 MCP 的客户端指过来 —— Claude Code、Cursor、Windsurf， 或任何能走 Streamable HTTP 的工具 —— 你正在读的这本手册连同整个社区版块，就都出现在那个客户端里了。 不用打开浏览器就能查某个节点有哪些输入，能检索是否已经有人遇到过同样的报错，没有的话可以直接发帖提问。

需要的东西只有三样：一个访问令牌、三行配置，以及一次用来确认连通的调用。

你能得到什么

端点只有一个地址 https://chenghub.org/mcp，它按照与网站完全相同的规则暴露相同的数据。 它是一层传输，不是第二个应用：可见性、校验和限流都与网页端一致， 并且它不会给出你的账号本来没有的任何能力 —— 没有审核、没有管理、没有删除，也不能管理账号或令牌。

具体来说，接好的客户端可以：

• 阅读文档 —— 浏览目录并取回任意一篇文章的全文，中英文皆可。
• 检索社区 —— 列出、搜索并阅读帖子及其评论串。
• 参与讨论 —— 发帖、评论、支持某个需求、点赞或收藏，以及举报违规内容。
• 搬运工作流 —— 读取他人分享的、已脱敏的工作流文档，或把自己的分享出去。

第一步 —— 创建访问令牌

在浏览器里登录 ChengHub，打开账号页，找到 MCP 那一节。选择有效期，创建令牌并复制。 这一步有两点要特别注意：

• 令牌只显示一次。 服务端不会再展示第二遍，关掉对话框之前一定要先复制。
• 创建令牌必须有浏览器登录态。 按设计，不能用另一个令牌来签发新令牌。

令牌默认有效期 90 天，另外可选 7、30、180、365 天。你随时可以在同一页面吊销它， 而且吊销会在已连接客户端的下一次请求上立即生效 —— 鉴权是每次调用都做，而不是开会话时做一次。

请选择「完全访问」这个 scope。 另一个选项「仅文档」并不是「可以读手册」的意思 —— 它是给文档管理员用的维护凭据，在端点的其他地方一律被拒。 用普通的完全访问令牌读文档完全没有问题。如果你发现每次调用都被拒，多半就是这个原因。

第二步 —— 把服务器加进客户端

每个客户端要填的都是同样三样东西：URL、Authorization 请求头，以及 HTTP 传输方式。 区别只在字段名。

Claude Code，写在项目根目录的 .mcp.json 里：

{
  "mcpServers": {
    "chenghub": {
      "type": "http",
      "url": "https://chenghub.org/mcp",
      "headers": {
        "Authorization": "Bearer <your-access-token>"
      }
    }
  }
}

Cursor，写在 ~/.cursor/mcp.json 里 —— 远程服务器不需要 type 字段， 而且它能从环境变量读令牌，不必把值留在文件里：

{
  "mcpServers": {
    "chenghub": {
      "url": "https://chenghub.org/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CHENGHUB_TOKEN}"
      }
    }
  }
}

Windsurf，它把这个字段叫 serverUrl：

{
  "mcpServers": {
    "chenghub": {
      "serverUrl": "https://chenghub.org/mcp",
      "headers": {
        "Authorization": "Bearer <your-access-token>"
      }
    }
  }
}

其他客户端同样可用，只要它能向 Streamable HTTP 端点发送 bearer 请求头。 端点默认是无状态的，因此没有会话需要保活，也不存在断线重连的问题。

第三步 —— 验证连接

让客户端调用 me 工具，它会返回当前令牌所属的 ChengHub 身份。 只要拿回的是你自己的账号，后面的一切就都能用。

这一步失败，几乎总是请求头的问题。过期、被吊销或格式不对的令牌， 在请求被当作 MCP 解析之前就已经被拒 —— 所以坏令牌的表现是「一个工具都没有」，而不是某次调用报错。 这里没有匿名模式。

你可以做什么

一共 26 个工具，分三组。

另有三个文档工具 —— doc_list_untranslated、doc_revisions、doc_upsert —— 是给维护这本手册的人用的。它们要求管理员角色，普通令牌调用不会得到有用的结果。

有两个习惯值得教给你的客户端。发帖之前，先用打算用的标题调一次 post_similar： 如果这个问题已经有人提过，在原帖上 post_support 比再发一个近似帖有价值得多。 参与讨论之前先调 comment_list —— 显而易见的那个问题，帖子里通常已经有答案了。

少踩坑的几条规则

创建类操作不可安全重试。 post_create、comment_create、两个举报工具以及 workflow_share_create 每次调用都会产生一条新记录。如果其中一个看起来超时了，不要直接再调一次 —— 先用 post_my_list、comment_list 或 my_reports 查一下记录是否已经建好。 post_support、post_set_reaction 和 comment_set_like 是幂等的，重复调用无妨。

「未找到」的意思是「你看不到」。 对调用者隐藏的内容一律报 NOT_FOUND，而不是 FORBIDDEN。 查不到某个帖子，并不能证明它从未存在。

举报是请人来看。 它不会隐藏任何内容，也不会触发任何自动下架。

翻译会回落。 当你要的语言还没有译文时，doc_detail 会返回源语言版本， 并通过让 locale 与 requested_locale 不一致来告诉你这件事。 在断定「中文版存在」之前，先比对这两个字段。

配额与上限

每分钟的额度把工具发现和工具调用算在一起，因为智能体循环的速度远快于人点击。 分页上限的存在是为了让一次响应不至于塞满模型的上下文窗口； 列表被截断时，请翻页，而不是去调大 limit。

令牌安全

令牌就等于你的账号，客户端用它做的任何事都会记在你名下。

• 绝对不要提交进版本库。 存有真实令牌的配置文件应当写进 .gitignore。 Cursor 的 ${env:VAR} 写法把值挡在文件之外，从根上避免了这个问题。
• 一台机器一个令牌。 这样丢一台笔记本只需吊销一个，而不是到处换。
• 一旦泄露，立刻吊销。 把令牌贴进聊天、工单或截图都算泄露。 吊销即时生效且没有代价；已连接的客户端会在下一次调用时失败，你换一个新令牌贴进去即可。
• 无人值守的场景请选更短的有效期。 90 天对你自己的终端是合理默认值， 对一台你之后会忘掉的机器则不是。

故障排查

下一步

• 接入 MCP Server
• ChengOS 是什么
• 常见问题