MCP 接入 · Most.Box

开始使用

先启动 MostBox daemon，再用当前身份在管理台创建独立凭证。每个凭证都有自己的 scope、有效期和允许发布目录。

打开 MCP 客户端管理

连接方式

Streamable HTTP

http://127.0.0.1:1976/mcp

适合 Codex、VS Code 等支持远程 MCP URL 的客户端。端点只接受本机回环请求。

stdio

npx -y most-box@latest mcp

适合 Claude Desktop 等进程型客户端。命令只连接已经运行的 daemon，不会启动第二个 P2P 引擎。

客户端配置

令牌只在创建时显示一次。使用环境变量或客户端的密码输入，避免把令牌写进仓库。

Codex

export MOSTBOX_MCP_TOKEN='<token>'
codex mcp add mostbox \
  --url http://127.0.0.1:1976/mcp \
  --bearer-token-env-var MOSTBOX_MCP_TOKEN
codex mcp list

Claude Desktop

{
  "mcpServers": {
    "mostbox": {
      "command": "npx",
      "args": ["-y", "most-box@latest", "mcp"],
      "env": {
        "MOSTBOX_URL": "http://127.0.0.1:1976",
        "MOSTBOX_MCP_TOKEN": "<token>"
      }
    }
  }
}

VS Code

{
  "inputs": [
    {
      "type": "promptString",
      "id": "mostbox-token",
      "description": "MostBox MCP token",
      "password": true
    }
  ],
  "servers": {
    "mostbox": {
      "type": "http",
      "url": "http://127.0.0.1:1976/mcp",
      "headers": {
        "Authorization": "Bearer ${input:mostbox-token}"
      }
    }
  }
}

权限与能力

客户端只能发现凭证 scope 允许的 resources 和 tools。发布权限还受允许目录约束。

Scopes

Scope	授予能力
`node:read`	读取节点状态、容量、网络与 holding
`files:read`	读取文件元数据、下载任务并检查分享链接
`files:publish`	发布允许目录中的 daemon 主机文件
`files:download`	发起 CID 校验下载并在成功后自动做种
`downloads:cancel`	取消当前用户的活动下载任务

Resources

URI	内容
`mostbox://node/status`	节点、网络、容量与做种摘要
`mostbox://files`	当前用户文件元数据
`mostbox://holdings`	本机完整 CID 副本和 topic 状态
`mostbox://downloads`	当前用户活动下载任务

Tools

Tool	行为
`mostbox_node_status`	读取节点、网络、容量与做种状态
`mostbox_list_files`	分页列出当前用户文件元数据
`mostbox_list_holdings`	分页列出本机完整副本
`mostbox_check_download`	检查 most:// 链接和在线可用性
`mostbox_get_share_link`	按文件 CID 返回规范分享链接
`mostbox_list_downloads`	列出活动下载任务
`mostbox_publish_local_file`	发布授权目录中的本机文件
`mostbox_start_download`	下载、校验并自动做种
`mostbox_cancel_download`	取消当前用户的下载任务

安全边界

HTTP MCP 只接受回环请求；远程节点应先通过 SSH 隧道映射到本机。
令牌绑定用户、scope 和有效期，撤销或删除后已有连接也不能继续调用。
发布路径必须是允许目录内的普通文件；符号链接逃逸、目录和特殊文件会被拒绝。
下载仍会重算 UnixFS CID v1；只有与链接一致的内容才会保存并自动做种。
Resources 只返回有界结构化元数据，不把任意大文件内容送入模型上下文。

常见问题

无法连接 daemon: 确认 daemon 正在运行，并访问 http://127.0.0.1:1976/api/node/status 检查状态。
令牌无效或已过期: 在管理台检查凭证状态。明文令牌无法再次查看，需要删除旧凭证并创建新凭证。
工具没有出现: 工具列表按 scope 生成。为客户端创建包含所需 scope 的新凭证。
文件发布被拒绝: 确认路径位于 files:publish 凭证的允许目录内，而且目标是 daemon 主机上的普通文件。