在 Claude Code 中连接 FolderSpan

Claude Code 可以通过 Streamable HTTP 使用 FolderSpan MCP 工具。本教程将连接保存到 Claude Code 的用户级配置，使其在当前用户的所有项目中可用。

准备连接信息

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

https://127.0.0.1:52137/mcp

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

添加 MCP 连接

先通过隐藏输入把完整令牌读入当前终端：

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

再添加用户级 MCP 服务器：

claude mcp add --transport http --scope user \
  folderspan 'https://127.0.0.1:52137/mcp' \
  --header "Authorization: Bearer ${FOLDERSPAN_MCP_TOKEN}"
unset FOLDERSPAN_MCP_TOKEN

该命令不会把完整令牌写入 shell 历史，但 Claude Code 会把请求头保存到当前用户的私有配置中。不要复制或提交该配置文件。

验证连接

查看服务器详情和连接状态：

claude mcp get folderspan
claude mcp list

正常情况下，claude mcp list 会将 folderspan 显示为 Connected。在 Claude Code 会话中输入 /mcp，也可以查看连接状态和已加载的工具。

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

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

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

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

常见问题

返回 HTTP 401

请求头中的令牌不完整，或者令牌已被禁用、重新生成或删除。移除 folderspan 连接后，使用新的完整令牌重新添加。

HTTPS 证书校验失败

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

仅在可信且隔离的局域网中，可以移除现有连接，再把添加命令中的 URL 改为：

http://127.0.0.1:52137/mcp

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

状态为 Failed to connect

• 确认 FolderSpan MCP 服务已开启，端口仍为 52137。
• 运行 claude mcp get folderspan，检查 URL 和请求头是否存在。
• 确认防火墙没有阻止 Claude Code 访问 FolderSpan 的 MCP 端口。
• 如果刚修改服务器或令牌，重新打开 Claude Code 会话后再检查 /mcp。

看不到 FolderSpan 工具

• 检查访问令牌权限。FolderSpan 只通过 tools/list 返回该令牌有权调用的工具。
• 在 Claude Code 中输入 /mcp，确认 folderspan 已启用并连接成功。
• 如果配置使用项目级 .mcp.json，需要先在交互式 Claude Code 会话中批准该服务器。

工具返回 permission_denied 或 not_connected

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

移除连接

claude mcp remove --scope user folderspan

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

更多 Claude Code MCP 配置项请参阅 Anthropic 官方 MCP 文档。