跳到主要内容

MCP 服务

FolderSpan 可以在当前设备上运行 MCP（Model Context Protocol）服务，让受信任的 AI 客户端或自动化程序在同一网络中发现并调用文件、书签、收藏、任务、设备、网络位置和同步工具。

MCP 服务支持 Android、桌面版和 iOS，使用 Streamable HTTP 传输；网页版不能接收入站 MCP 连接。服务默认使用端口 52137，不提供 stdio 传输。完成连接后，请继续阅读 MCP 工具使用。第三方客户端请参阅 Codex 接入教程 或 Claude Code 接入教程。

MCP 页面总览

页面结构（按截图编号）​

  1. MCP 服务：开启或关闭服务，并设置客户端使用的连接端口。
  2. 访问令牌：点击右侧 + 新建访问令牌。
  3. 令牌卡片：查看令牌名称和权限级别，启用或停用令牌，并展开管理操作。
  4. 允许局域网连接：开启后，同一网络中的其他设备可以连接 MCP 服务。
  5. 选择地址：选择生成连接地址时使用的本机 IP。
  6. 连接协议：在 HTTP 和 HTTPS 之间切换；建议优先使用 HTTPS。
  7. 连接信息：查看或复制推荐地址、单次请求地址和安全指纹，也可以显示连接二维码。

工作方式​

  1. 在 FolderSpan 的 工具箱 中打开 MCP，开启独立的 MCP 服务。
  2. 创建访问令牌，并只授予客户端完成任务所需的权限。
  3. 第三方客户端使用页面中显示的连接地址和 Bearer Token 建立连接。
  4. 客户端通过 tools/list 发现当前令牌可用的工具，再根据你的提问调用工具。具体示例参阅 MCP 工具使用。

未获得对应权限的工具不会出现在 tools/list 结果中；即使客户端直接调用，也会在执行操作前被拒绝。

页面操作说明​

1. 开启 MCP 服务​

在 工具箱 中进入 MCP，确认 连接端口 后开启 MCP 服务。页面显示 已开启 时，已启用的访问令牌可以通过下方地址连接服务。

修改端口后，客户端中的连接地址也需要同步更新。

2. 新建访问令牌​

点击 访问令牌 右侧的 +，在“新建令牌”弹窗中填写名称。然后选择 仅查看、查看并操作 或 完全控制，也可以继续调整各类功能的具体权限。确认后点击 保存。

新建访问令牌

令牌创建后会显示“保存好这段令牌”弹窗。点击复制按钮或 复制令牌 保存完整令牌；关闭弹窗后无法再次查看。如果令牌丢失，只能生成新令牌。

保存新建的访问令牌

注意

完整令牌相当于访问凭据。不要把它粘贴到聊天内容、截图或公开文档中，只应保存到受信任客户端的 MCP 配置中。

3. 管理访问令牌​

令牌卡片右侧的开关用于启用或停用令牌。点击展开按钮后，可以选择 编辑、生成新令牌 或 删除。

管理访问令牌

停用令牌会拒绝该令牌的新请求，但不会删除令牌配置。需要恢复使用时，再次开启即可。

4. 编辑访问令牌​

展开令牌卡片并点击 编辑，可以修改令牌名称、常用权限和具体操作权限。调整完成后点击 保存；现有令牌值不会改变。

编辑访问令牌

5. 生成新令牌​

令牌疑似泄露或已经丢失时，展开令牌卡片并点击 生成新令牌。在确认框中点击 重启 后，旧令牌会立即失效，使用该令牌的客户端需要改用新令牌。

确认生成新令牌

6. 删除访问令牌​

展开令牌卡片并点击 删除，再在底部确认提示中点击 删除。删除后客户端会立即失去访问权限，且无法恢复。

删除访问令牌

使用工具​

连接成功后，可以直接用自然语言让 AI 查看或管理 FolderSpan 中的文件、书签、收藏、任务、设备、网络位置和同步任务。每类工具的提问示例、返回字段、权限和错误处理统一放在 MCP 工具使用 中。

连接地址​

MCP 页面同时显示 HTTPS 和 HTTP 地址，并优先显示 HTTPS。两种协议使用相同的公开端口。

页面名称路径适用场景
推荐地址/mcp有状态 Streamable HTTP。适用于大多数 MCP 客户端，支持 POST、GET/SSE 和 DELETE。
单次请求地址/mcp/stateless无状态、仅 POST。适用于明确支持单次请求模式的客户端或调试请求。

有状态连接会返回 Mcp-Session-Id。会话空闲超过 30 分钟后失效，每个访问令牌最多同时保留 32 个活动会话。服务支持 MCP 协议版本 2025-06-18 和 2025-11-25，初始化时会协商双方共同支持的新版本。

注意

HTTP 不会加密 Bearer Token、文件路径和请求参数，只应在可信局域网中使用。优先选择 HTTPS，并在客户端要求确认设备证书时核对 MCP 页面显示的 安全指纹。

1. 允许局域网连接​

默认只有当前设备可以连接 MCP 服务。其他设备需要访问时，开启 允许局域网连接，并确保客户端与 FolderSpan 所在设备处于同一可信网络。

允许局域网连接 MCP 服务

2. 选择连接地址​

点击 选择地址，从本机可用地址中选择生成连接地址时使用的 IP。客户端与 FolderSpan 在同一设备上时，可以选择 127.0.0.1 或 ::1；从局域网中的其他设备连接时，应选择该网络中的实际 IP 地址。

选择 MCP 连接地址

3. 复制或扫码连接​

在连接信息中点击复制按钮，可复制地址或安全指纹；点击推荐地址旁的二维码按钮，会显示“扫码连接”弹窗。二维码和下方文本包含同一个推荐地址。

扫码连接 MCP 服务

安全边界​

  • 每个请求都必须携带 Authorization: Bearer <完整令牌>。
  • files.read、files.write 或 files.share 权限不能绕过敏感路径保护。
  • 文件工具会检查端点能力、设备路径权限、规范化路径边界和符号链接，拒绝越过授权根目录的访问。
  • 受保护条目即使能从已授权的父目录列表中看到，也不会暴露读写、重命名、删除或分享能力，且不能直接读取元数据和内容。
  • 错误和日志不会返回令牌、保存的凭据、文件内容或被拒绝的目标路径。
  • 带有非回环 Origin 的浏览器请求会被拒绝，以避免网页跨站调用和 DNS 重绑定攻击。

建议为每个第三方客户端单独创建令牌，并优先使用 仅查看 或自定义权限。客户端不再使用时，可以在 MCP 页面禁用或删除对应令牌；生成新令牌后，旧令牌会立即失效。