跳到主要内容

在 Codex 中连接 FolderSpan

Codex CLI、Codex IDE 扩展和 ChatGPT 桌面应用可以通过 Streamable HTTP 使用 FolderSpan MCP 工具。它们共享同一台 Codex 主机上的 MCP 配置。

准备连接信息​

  1. 在 FolderSpan 中打开 工具箱 > MCP，开启 MCP 服务。
  2. 新建访问令牌。首次接入建议选择 仅查看，确认连接正常后再按需增加权限。
  3. 复制页面显示的 推荐地址 和完整令牌。推荐地址以 /mcp 结尾，例如：
https://127.0.0.1:52137/mcp

完整令牌只显示一次。请将其保存在本机环境变量或密码管理器中，不要写入项目文件、命令历史或聊天内容。有关提问方式、返回内容和工具权限的完整说明，请参阅 MCP 工具使用。

使用 Codex CLI 添加连接​

先在启动 Codex 的同一环境中设置令牌：

read -rsp 'FolderSpan MCP Token: ' FOLDERSPAN_MCP_TOKEN
export FOLDERSPAN_MCP_TOKEN
printf '\n'

再添加 MCP 服务器，将 URL 替换为 FolderSpan 页面显示的真实地址：

codex mcp add folderspan \
  --url 'https://127.0.0.1:52137/mcp' \
  --bearer-token-env-var FOLDERSPAN_MCP_TOKEN

该命令会把连接写入 ~/.codex/config.toml，但不会把令牌写入配置文件。等价配置如下：

[mcp_servers.folderspan]
url = "https://127.0.0.1:52137/mcp"
bearer_token_env_var = "FOLDERSPAN_MCP_TOKEN"

如果从桌面图标启动 Codex，需要确保桌面应用进程也能读取 FOLDERSPAN_MCP_TOKEN；只在某个终端中执行 export 不会影响已经运行的桌面应用。

验证连接​

查看 Codex 已保存的 MCP 服务器：

codex mcp get folderspan
codex mcp list

保存配置后，重启 Codex 桌面应用或 IDE 扩展；Codex CLI 则新建一个会话。在 Codex TUI 中可以输入 /mcp 查看连接状态和已加载的工具。

连接成功后，可以先执行只读验证：

请使用 FolderSpan MCP 列出当前在线设备，不要执行任何修改操作。

如果令牌包含 files.read 权限，也可以指定来源和绝对路径：

请使用 FolderSpan MCP 列出 Local 来源中 /Documents 的直接子项，只返回名称、类型和大小。

常见问题​

返回 HTTP 401​

确认 FOLDERSPAN_MCP_TOKEN 包含完整令牌，并且启动 Codex 的进程能够读取该变量。令牌被禁用、重新生成或删除后，也需要更新环境变量并重启 Codex。

HTTPS 证书校验失败​

FolderSpan 使用设备证书保护 HTTPS 连接。如果 Codex 不信任该证书，应优先把证书加入操作系统或 Codex 使用的 CA 信任链。不要全局关闭 TLS 校验。

仅在可信且隔离的局域网中，可以临时改用 FolderSpan 页面显示的 HTTP 地址：

codex mcp remove folderspan
codex mcp add folderspan \
  --url 'http://127.0.0.1:52137/mcp' \
  --bearer-token-env-var FOLDERSPAN_MCP_TOKEN

HTTP 会明文传输令牌、文件路径和工具参数，不应跨公网或不可信网络使用。

看不到 FolderSpan 工具​

  • 新增 MCP 后应重启客户端或新建 Codex 会话；当前会话不会动态加载新工具。
  • 运行 codex mcp get folderspan，确认服务器处于启用状态且 URL 正确。
  • 检查访问令牌权限。FolderSpan 只通过 tools/list 返回该令牌有权调用的工具。
  • 确认防火墙和访客网络没有阻止 Codex 设备访问 FolderSpan 的 MCP 端口。

工具返回 permission_denied 或 not_connected​

permission_denied 表示令牌权限、敏感路径或设备路径授权不允许该操作；not_connected 表示目标设备、分享来源或网络位置当前未连接。先在 FolderSpan 中修正权限或连接状态，再让 Codex 重试。

移除连接​

codex mcp remove folderspan

不再使用该客户端时，还应在 FolderSpan 的 MCP 页面禁用或删除对应令牌。

更多 Codex MCP 配置项请参阅 OpenAI 官方 MCP 文档。