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

声明:Carbon Forge 由 100monkeys.ai 开发,因此请把这篇指南当作开发方的说明来读。它由我们的一个 AI 智能体起草,并经公司审阅;这个简体中文版是英文原版指南的译文。Carbon Forge 的步骤引用公开文档(英文);每个客户端的配置都复制自该客户端自己的文档,链接附在旁边。引文保留英文原文,译文附在旁边。最后一节列出文档没有回答的问题。

你要搭建的是什么

一个工作区,多个客户端,每个一个令牌。Carbon Forge 服务器使用 Streamable HTTP,"binds every call to a workspace via a bearer token"(通过 bearer 令牌把每次调用绑定到一个工作区),并且 "tools honor the cap exactly as a human session does: there is no agent-only privilege"(工具对权限上限的遵守与人类会话完全一样:没有智能体专属的特权)(MCP overview)。任何能发送 HTTP 头的客户端都能接入。Claude Code 有自己的指南:通过 MCP 把 Claude Code 连接到 Carbon Forge。

第 1 步:每个客户端签发一个令牌

在 carbonforge.dev/login 登录,打开设置,选择 API tokens,选定工作区、角色上限和工具范围,并且 "name the token after the agent or environment that will hold it"(用将持有它的智能体或环境给令牌命名)(MCP tokens)。每个客户端一个令牌,意味着审计日志(它记录 "every tool call ... under the token identity",即以令牌身份记录每一次工具调用)能告诉你哪个工具做了什么,而且你可以吊销其中一个而不影响其他。

按用途选择范围(MCP token scopes):做笔记的助手用 Basic LLM memory,只读的用 Read-only memory 或 SCM reader,在 lane 上写代码的用 SCM agent。文档建议:"Default to the narrowest preset that still covers what the client needs."(默认选择仍能覆盖客户端所需的最窄预设。)

第 2 步:把每个令牌放在环境变量里

密钥 "is shown once, then only the prefix."(只显示一次,之后只显示前缀。)下面两个客户端都能从环境变量读取它,所以它不会出现在最终进入提交的配置文件里:

export CARBON_FORGE_TOKEN=‹token for this client›

第 3 步:配置 Cursor

Cursor 从 mcp.json 读取 MCP 服务器:对所有项目是 ~/.cursor/mcp.json,对单个项目是 .cursor/mcp.json。远程服务器接受 url 和 headers,Cursor 在两者中都会解析 ${env:NAME}(Cursor MCP docs):

{
  "mcpServers": {
    "carbon-forge": {
      "url": "https://carbonforge.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CARBON_FORGE_TOKEN}"
      }
    }
  }
}

第 4 步:配置 Codex

Codex 把 MCP 服务器保存在 ~/.codex/config.toml,或受信任项目中的 .codex/config.toml。Streamable HTTP 服务器接受 url,而 bearer_token_env_var 指定 "environment variable name for a bearer token to send in Authorization"(要在 Authorization 中发送的 bearer 令牌的环境变量名)(Codex MCP docs):

[mcp_servers.carbon_forge]
url = "https://carbonforge.dev/api/mcp"
bearer_token_env_var = "CARBON_FORGE_TOKEN"

第 5 步:配置其他 MCP 客户端

关于 Claude Desktop,Carbon Forge 文档说:"add an MCP server entry pointing at the instance URL with the token in the Authorization header."(添加一个指向实例 URL、在 Authorization 头中带令牌的 MCP 服务器条目。)关于 IDE 插件:"point the plugin at the same MCP endpoint; Streamable HTTP works over plain HTTPS."(把插件指向同一个 MCP 端点;Streamable HTTP 在普通 HTTPS 上即可工作。)无论客户端的文件格式如何,要填的就是这三个值:

Endpoint:  https://carbonforge.dev/api/mcp
Transport: Streamable HTTP
Header:    Authorization: Bearer ‹token for this client›

第 6 步:用 cortex.ground 检查每个客户端

让每个客户端调用 cortex.ground。它返回 "the calling identity, what the bearer can do, what is reachable"(调用者身份、令牌持有者能做什么、能访问到什么)(cortex.ground)。比较各个回答:每个客户端都应显示同一个工作区,以及其范围允许的能力。令牌错误的客户端会被拒绝;文档说错误的令牌会被 "refused outright rather than quietly treated as anonymous"(直接拒绝,而不是悄悄当作匿名处理)。

第 7 步:每次调用都指明工作区

每个令牌记住自己的当前工作区,所以 "every agent has its own active workspace and they do not collide"(每个智能体都有自己的活动工作区,彼此不会冲突)(MCP token scopes)。这也意味着两个客户端可能悄悄指向不同的工作区。告诉每个智能体在每次调用时都传入 workspace;工具接受这个参数,而且它从不移动指针。

第 8 步:给每个写入的智能体一条自己的 lane

共享的笔记是页面;客户端真正会冲突的是共享的代码。在 Carbon Forge 中,智能体不是克隆仓库,而是开一条 lane:"A lane costs nothing to open and holds no copy, so one per task, or one per agent, is the expected use"(开一条 lane 没有成本,也不持有副本,所以每个任务或每个智能体一条,是预期的用法)(Working in lanes)。Carbon Forge 从不自行合并文本;不再适用的补丁会作为有名字的冲突返回,而一次落地就是一个 changeset,要么全部,要么没有。Cursor 的智能体和 Codex 可以在同一个 trunk 上工作,它们之间不会发生悄无声息的合并。

文档没有回答的问题

针对具体客户端的配置。Carbon Forge 文档对 Claude Desktop 和 IDE 插件各只有一句话,没有给出 Cursor 或 Codex 的文件;上面的片段来自 Cursor 和 Codex 的文档。
部署在自有主机或自定义域名上的实例,其端点没有说明;文档给出的是 https://carbonforge.dev/api/mcp。
How MCP works 页面展示的 curl 调用指向 /mcp,而匿名访问页面使用 /api/mcp。
令牌是否会自动过期没有说明;如何吊销有说明。
没有提到 MCP 客户端的 OAuth 登录;文档给出的方法是 bearer 令牌。

把 Cursor、Codex 和任意 MCP 客户端连接到同一个 Carbon Forge 工作区