MCP 服务器

Model Context Protocol 是一个开放标准，用一套很小的 JSON-RPC 接口把工具、提示词和数据暴露给 AI 智能体。服务端只要实现一次——一个 GitHub 服务器、一个 Postgres 服务器、一个文档服务器——任何支持 MCP 的客户端就都能用。ORG-2 正是这样一个客户端：它连接你配置的服务器，把它们的工具与内置工具一起并入该会话的注册表，并把每一次调用记进同一条轨迹。本页讲怎么连接服务器、怎么划定它们的作用域、怎么给它们喂凭据，以及它们起不来的时候怎么修。

传输方式

ORG-2 支持三种传输方式，由配置里的 type 字段决定用哪一种：

初次握手必须在 timeout 秒内完成，默认 30 秒。服务器是在会话启动时于后台连接的，所以某个服务器慢，拖住的只是它自己的工具，而不是整个会话。

通过界面添加服务器

1. 打开 设置 → Skills, MCPs & Plugins，选择 MCP 标签页。工具栏和 Spotlight 里也都有添加 MCP 服务器，是通往同一处的快捷入口。
2. 点添加 MCP 服务器。
3. 填服务器名称——「此 MCP 服务器的唯一标识符」。它会出现在该服务器提供的每一个工具里，所以尽量写短。
4. 选一种传输方式：stdio、SSE 或 Streamable HTTP。
5. 选一个作用域：User 或 Repo-specific。这个字段的帮助文字点明了它写入的文件：~/.orgii/mcp-servers.json 或 <repo>/.orgii/mcp-servers.json。
6. 对 stdio，填命令（例如 npx）、参数（采用 shell 引号语法，例如 -y @modelcontextprotocol/server-filesystem /tmp）、可选的工作目录，以及以键/值行填写的环境变量。对 SSE 或 Streamable HTTP，填 URL 和需要的 Headers。
7. 可选地设置自动批准的工具和连接超时（秒），并保持启用打开。
8. 点测试连接。成功时会显示「连接成功」以及发现到的工具数量。然后点保存。

已经在别处配置过服务器？表格下方的从其他应用导入 MCP servers 面板会在你的仓库里扫描 .cursor/、.claude/ 和 .vscode/ 下的 mcp.json 与 mcp-servers.json，在用户级扫描 ~/.cursor/ 和 ~/.claude/，并把找到的每一项列出来供你导入。

配置文件

两种作用域用的是同一套 schema，在 mcpServers 下以服务器名为键：

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/notes"],
      "disabled": false,
      "timeout": 30
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" },
      "autoApprove": ["search_repositories", "get_file_contents"]
    },
    "docs": {
      "type": "streamableHttp",
      "url": "https://${MCP_HOST:-api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${MCP_TOKEN}" },
      "disabled": false,
      "timeout": 60
    }
  }
}

除 type 之外，每个字段都是可选的；disabled 默认为 false，timeout 默认为 30。格式损坏的文件绝不会被悄悄覆盖——ORG-2 拒绝覆盖它解析不了的 JSON，而是转而报告 Failed to parse MCP config <path>。

凭据与环境变量

不要把密钥粘进配置文件。字符串字段支持 shell 风格的展开，所以文件里可以引用 ORG-2 所处运行环境中的变量：

• ${VAR} —— 展开；变量未设置或为空时报错。
• ${VAR:-default} —— 变量未设置或为空时回退到 default。
• 不带花括号的 $HOME 保持字面量，匹配不上的写法原样透传。

展开作用于 command、args 的每个元素、env 里的值、url，以及 headers 里的值。它有意不作用于 cwd，这样目录名就不会变成藏密钥的地方。

对于走 OAuth 的远程服务器，ORG-2 会自己把流程跑完，而不是向你要 token。当某个服务器报告它需要认证时，它的状态会变成需要授权，而它此时唯一提供的工具是 mcp__<server>__authenticate。调用这个工具会绑定一个本地回调、打开你的浏览器、以 ORGII MCP Client 的身份把 ORG-2 注册到身份服务商、最多等待十分钟、把凭据存到本地，然后重连该服务器，让它真正的工具出现。这个「需要认证」状态会缓存 15 分钟，免得每次会话都去猛敲一个尚未认证的服务器。stdio 服务器用不了这套流程——请改用 env 给它们做认证。

User 作用域与 Repo-specific 作用域

User 服务器存放在 ~/.orgii/mcp-servers.json，在每个工作区都会加载。Repo-specific 服务器存放在 <repo>/.orgii/mcp-servers.json，只对该仓库里的会话加载，适合放项目专属的数据库或问题跟踪系统。

当同一个名字在两个文件里都存在时，连接细节以仓库那一份为准——命令、URL、环境变量、Headers。disabled 是例外：它取两个文件的逻辑或，所以在用户级关掉的服务器，即便仓库配置又声明了一遍，也仍然是关的。表格的作用域筛选器（全部 / User / Repo-specific）反映的是同一种划分。

注意： repo 作用域的条目是在该仓库里启动会话时读取的。如果从设置界面看 Repo-specific 标签页是空的，就直接编辑 <repo>/.orgii/mcp-servers.json——schema 相同，下一次会话即生效。

没有按会话挑选服务器的选择器。会话继承的是合并之后的配置，再减去它的智能体禁用掉的那些。

决定一个智能体拿到哪些工具

每个服务器的工具都以完全限定名注册，即 mcp__<server>__<tool> —— 分隔符是双下划线，字母、数字、连字符和下划线以外的字符一律改写成 _。模型调用的是这个名字，轨迹记录的是这个名字，下文用到的标识符也是它。界面上会去掉前缀，只显示裸的工具名。

三个层级的控制：

• 整台服务器。 MCP 表格里每一行上的启用开关，或者批量的全部启用 / 全部禁用操作。禁用会把 disabled: true 写进拥有该条目的那个文件，并停掉进程。
• 按智能体、按服务器或按工具。 智能体的配置里会列出你的服务器；展开其中一个，就能逐个工具设开关。这些写进智能体定义，而且排除项是继承的——派生出来的智能体可以再加排除，但去不掉父级的排除。
• 工作区资源。 智能体上的自动加载工作区 Skills、MCP 和插件开关决定 repo 作用域的服务器到底加不加载。关掉之后，用户级的服务器照样加载。

autoApprove 字段列出会在会话启动时被标记为预先批准的工具名——填 * 表示全部；向导里给的提示是「留空则每次调用都确认。」

提示词与资源

服务器能提供的不止是工具。如果一个已连接的服务器发布了提示词，就可以在聊天输入框里用 /mcp__<server>__<prompt> 加位置参数来调用它：ORG-2 会把这些参数与提示词声明的参数名一一对应，在服务端渲染出提示词，并在发送前用结果替换掉你的消息。如果服务器发布了资源，ORG-2 会注册两个全局工具——list_mcp_resources 和 read_mcp_resource——它们把服务器名当作参数传入，而不是每台服务器各配一对。

MCP 调用在轨迹里长什么样

一次 MCP 调用的记录方式和内置工具完全一样：完全限定的 mcp__server__tool 名称、完整的参数、完整的结果，日后全都可以检索。在聊天面板里，它渲染成一个带 MCP 图标和裸工具名的工具块。

会上报进度的服务器，会在那个块里多出一行实时进度——总数已知时是一个百分比和 n / total 计数，未知时是一个跳动的指示器和一个原始计数——结果到达后这一行就消失。失败则以 MCP 服务器错误块的形式呈现。MCP 的工具定义在上下文用量明细里也会单独归到 MCP 类别下，连了很多服务器时值得看一眼。

排查起不来的服务器

每个服务器都会显示六种状态之一：

按这个顺序往下排查：

1. 等一会儿。 首次启动时，stdio 服务器往往得先下载它的包。表格会显示「正在启动 N 个 MCP server…(初次启动可能需要数秒)」，十秒之后再显示「仍在连接…」。
2. 重启它。 行上 ⋯ 菜单里的重启，或者详情面板里的重新连接，都会在不动配置的前提下重跑一次握手。
3. 读错误信息。 打开该服务器，看状态区：Failed to connect to MCP server '<name>' 会原样带上底层原因。
4. 测试配置。 在向导里重新打开该服务器，点测试连接——它会用你改过的值去连，但不保存。对 stdio，还可以在终端里把 command 和 args 原样跑一遍——多数失败都是二进制文件缺失、路径写错，或者包压根没装。
5. 检查变量和超时。 如果错误里点名了某个未定义的环境变量，就把它导出到 ORG-2 看得见的地方，或者改用 ${VAR:-default}。如果只是服务器启动慢，那就把连接超时（秒）调大。
6. 校验 JSON。 Failed to parse MCP config <path> 说明文件格式坏了。用编辑器修好它——只要它还是坏的，ORG-2 就不会覆盖它。

会话过程中反复出现的传输层故障是自动处理的：同一条连接上出现三次终止性错误之后，ORG-2 会丢掉它并重新连接。仅仅是工具返回了一个错误不算在内，因为这时连接本身还是健康的。

下一步

• 工具 —— MCP 服务器所扩展的那套内置工具面。
• 智能体 —— 按智能体的工具策略，包括某个智能体可以使用哪些 MCP 服务器。
• Skills —— 扩展智能体的另一条路，给的是流程而不是工具。
• 安全 —— 审批提示，以及凭据存放在哪里。