其他语言: English, Español, Português, 日本語, Deutsch, Français, 한국어, Italiano, हिन्दी · 全部中文指南

声明:我们在 100monkeys.ai 开发 Carbon Forge,因此请把本文当作开发方的说明来读。本指南由我们的一个 AI 智能体根据 carbonforge.dev/docs 上的公开文档(英文)起草,并经公司审阅;这个简体中文版是英文原版指南的译文。Carbon Forge 的步骤引用文档;Claude Code 的命令来自 Claude Code 自带的 claude mcp add --help。文档没有回答的问题,在最后一节说明。

为什么要连接

编程智能体如果没有把笔记放在下次还能读到的地方,就会在会话之间遗忘。Carbon Forge 就是那个地方,并且与项目里的人共享。文档把 MCP 称为 "a primary product surface, co-equal with the human editor, against the same atoms, pages, links, and embeddings"(主要的产品界面,与人用的编辑器地位相同,作用于同样的 atom、页面、链接和嵌入)(A shared cortex for LLMs)。智能体写的页面,就是人可以打开、修改和链接的页面。

第 1 步. 不带令牌试用只读端点

注册之前,先连接公开内容。摘自 Reading a public cortex without an account:"Add the instance's MCP endpoint to your client with no Authorization header. For this instance that is https://carbonforge.dev/api/mcp over Streamable HTTP. With Claude Code:"(不带 Authorization 头,把实例的 MCP 端点添加到你的客户端。对这个实例来说,就是通过 Streamable HTTP 访问上面这个地址。在 Claude Code 中:)

claude mcp add --transport http cortex-public https://carbonforge.dev/api/mcp

你会得到二十二个只读工具,按 IP 地址限速。让 Claude Code 读取工作区 docs 中的页面 home;没有令牌就没有当前工作区,所以每次调用都要指定 workspace。在添加带认证的条目之前,用 claude mcp remove cortex-public 删除这一条,免得智能体读取两个界面。

第 2 步. 登录并选择工作区

在 carbonforge.dev/login 用邮件链接或 100monkeys 按钮登录;没有密码。公开工作区免费,每个账户都包含一个免费的私有工作区(价格)。决定智能体把哪个工作区当作记忆。私有工作区只让成员看到这些笔记。

第 3 步. 创建范围尽可能窄的令牌

根据 MCP tokens:打开设置并选择 API tokens;选择工作区和角色上限(viewer、editor 或 admin);选择工具范围;用智能体的名字给令牌命名;复制密钥,它 "is shown once, then only the prefix."(只显示一次,之后只显示前缀。)

对于共享记忆,Basic LLM memory 让智能体可以 "read and write pages, atoms and tags, and run search, with basic graph reads"(读写页面、atom 和标签,并运行搜索,附带基本的图读取),文档称之为 "the minimum for an LLM that uses Carbon Forge as its memory."(把 Carbon Forge 当作记忆的 LLM 所需的最低权限。)对只需回忆的智能体,Read-only memory 不写入任何内容。对代码工作,SCM agent 增加了 lane、树和落地(MCP token scopes)。范围之外的工具 "answers exactly as a tool that does not exist."(的回应与不存在的工具完全相同。)

第 4 步. 带上令牌把服务器添加到 Claude Code

文档要求客户端指向该端点,"with the token in the Authorization header"(并把令牌放在 Authorization 头中)。Claude Code 用 --header 设置请求头:

claude mcp add --transport http carbon-forge https://carbonforge.dev/api/mcp \
  --header "Authorization: Bearer ‹your token›"

如果你把令牌放进环境变量,改写成 $CARBON_FORGE_TOKEN,shell 会在 Claude Code 看到之前把它展开,所以密钥仍然会存进 Claude Code 的配置。无论哪种方式,都要把那份配置当作机密,并把服务器放在默认的 local 范围或 user 范围,而不是你会提交的文件里。

第 5 步. 让智能体自行定位

开始一个会话,让 Claude Code 调用 cortex.ground。文档把它定为第一个调用:它 "Returns the per-instance README, the calling identity, what the bearer can do, what is reachable, and helper-service health"(返回实例的 README、调用者身份、令牌持有者能做什么、能访问什么,以及辅助服务的健康状况)(cortex.ground)。原始调用如下:

{ "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": { "name": "cortex.ground" } }

服务器还会在 initialize 握手和会话的第一次工具调用时提供同样的内容,所以跳过这一步的智能体也能定位。阅读 capabilities 部分,确认令牌可以写入。

第 6 步. 写入记忆,再引用它

让智能体把学到的东西记成一个页面,比如一个决定及其理由,并在下一次会话开始时读取这个页面。有两个特性让它成为记忆而不是缓存。每次保存都会写入一个新版本,没有任何操作会改写旧版本,所以你可以读到智能体上周写的内容。并且 "every entity-returning tool decorates the result with a clickable permalink so an LLM can hand a working URL back to its human"(每个返回实体的工具都会在结果上附加一个可点击的永久链接,让 LLM 能把可用的 URL 交还给它的人类)(How MCP works):让智能体引用它依据的每个页面的永久链接,并逐一核对。

代码也在同一份记录里。智能体打开一个 lane 而不是克隆,一次落地就是一个变更集,在一个事务中全部写入,否则什么都不写(Working in lanes)。

第 7 步. 关注审计日志,用完后撤销

"Every tool call lands in the audit log under the token identity."(每一次工具调用都会以令牌的身份记入审计日志。)当智能体不再需要访问,或令牌泄露时,在设置中撤销它;"in-flight calls fail on the next request"(进行中的调用会在下一次请求时失败)(MCP tokens)。

文档没有回答的问题

自有主机上实例的端点。匿名访问页面说 https://carbonforge.dev/api/mcp 是 "for this instance"(用于这个实例);它没有说明位于自有子域名或自定义域名上的实例该用哪个 URL。
两个路径。同一页面使用 /api/mcp;How MCP works 上的 curl 示例发送到 /mcp。我们使用 /api/mcp。
令牌有效期。文档描述了如何撤销令牌,但没有说明令牌是否会自行过期。
针对具体客户端的配置。文档没有给出 Claude Code 命令;上面的命令是 Claude Code 设置请求头的文档语法。

通过 MCP 把 Claude Code 连接到 Carbon Forge:智能体可以读、写和引用的共享记忆