reachpad-mcp

@reachpad/mcp

reachpad 让 Claude、Codex 和其他编码 Agent 在持久化工作区中构建全栈应用，并通过链接分享，无需单独部署。工作区是一台由 Agent 自行操作的云端开发计算机：其中的代码仓库、文件系统、已安装的依赖项和构建状态都会在多次调用之间保留，而不是用完即弃、转眼就忘的沙箱。进程是例外；详见下文。

这是 MCP 服务。它让 Claude、ChatGPT、Cursor、OpenCode 或你自己的 Agent 创建工作区、在其中运行命令、分叉工作区，并在之后继续使用，无需开发者一直开着笔记本电脑。

• 它会持久化。 暂停后，磁盘会被封存；下次调用时会从该封存状态启动，文件、已安装内容和 git 状态都完好保留，而不是重新构建。进程是例外：每次启动都必须冷启动。
• 它可以分叉。 从一个准备好的状态进行 20 次尝试，每次只需付出增量成本，而非重新构建 20 次——因为工作区是快照链，而不是一台机器。
• 它可以让密钥远离工作区。 代理式凭证会在边界处代你调用，其值永远不会进入工作区、日志或存储。如果将凭证写入工作区，则按设计可在其中读取。
• 它不依赖特定 Agent。 REST API 是规范接口；此服务、SDK 和 CLI 都是对它的封装。你可以使用自己的 Agent。

API 是产品边界，而不是 Web UI：reachpad.dev。

安装

npx -y @reachpad/mcp          # stdio, for a local client

在 Claude Code 中：

claude mcp add reachpad -e REACHPAD_IDENTITY_CREDENTIAL=… -- npx -y @reachpad/mcp

两种传输方式，一套实现

npx @reachpad/mcp                                  # stdio
REACHPAD_MCP_HTTP_PORT=8722 npx @reachpad/mcp      # streamable http

本地客户端通过 stdio 通信；远程连接器通过 Streamable HTTP 通信。工具和行为都相同——两种方式是新增而非分叉实现，因为同一接口的两套实现会逐渐偏离。

HTTP 端对 GET 返回 405：这里的每个工具都是请求/响应式的，规范允许拒绝由服务端发起的流，而不是为永远不会到来的流量保持连接打开。它没有会话——调用之间不保留任何无法通过重启重建的内容。它也不携带自己的凭证：授权 HTTP 请求的凭证，就是授权 reachpad 的凭证。

它默认经过身份验证。设置 REACHPAD_MCP_HTTP_TOKEN，该值就会成为 bearer token；如果不设置，则会为本次运行生成一个并打印到 stderr，因为一个能通过其背后的 run_command 桥接到你账户的端口，不应该对机器上的所有其他进程开放：

reachpad mcp: streamable http on http://127.0.0.1:8722
reachpad mcp: no REACHPAD_MCP_HTTP_TOKEN was set, so this one was generated for this run:

    Authorization: Bearer 3Qk…

reachpad mcp: it changes every restart. Set REACHPAD_MCP_HTTP_TOKEN to pin it, or
reachpad mcp: REACHPAD_MCP_HTTP_NO_AUTH=1 to serve with no authentication at all.

仍然可以在不进行身份验证的情况下提供服务，但现在必须明确声明：REACHPAD_MCP_HTTP_NO_AUTH=1。

配置

变量	含义
REACHPAD_ENDPOINT	你的 reachpad 主机。除回环地址外，任何明文 http:// 请求都会在打开套接字前被拒绝。
REACHPAD_IDENTITY_CREDENTIAL	你的个人凭证。它对应一个账户，不能代表其他账户执行操作——服务端从凭证自身的记录中获取身份，绝不从请求中获取。
REACHPAD_API_KEY	可选，按工作区限定范围且可撤销。设置后，run_command 会使用它，无需进行身份交换。
REACHPAD_MCP_HTTP_PORT	使用 HTTP 而非 stdio 提供服务。
REACHPAD_MCP_HTTP_HOST	默认为 127.0.0.1。此进程会使用你的凭证连接到控制平面，因此只有在经过终止 TLS 的代理保护时，才应有意将其绑定到公网。
REACHPAD_MCP_HTTP_TOKEN	bearer 令牌，使用恒定时间比较。若未设置，则会为本次运行生成一个令牌并打印到 stderr——不会因为缺少令牌而让端点变成未认证状态。
REACHPAD_MCP_HTTP_NO_AUTH	设为 1 后，服务将完全不进行身份验证：所有能够访问该端口的调用方都获准访问。这需要明确选择，并非默认设置。
REACHPAD_MCP_ALLOWED_ORIGINS	以逗号分隔。携带未列出的 Origin 的请求会被拒绝——浏览器无法伪造该值，从而阻止 DNS 重绑定。完全不带 Origin 的请求属于非浏览器客户端，会被允许。

如果设置了多个凭证，则优先使用权限范围最窄的凭证；凭证遭拒后绝不会改用权限范围更宽的凭证重试——回退会导致无人主动选择的权限提升。

工具

工具	功能
get_credit_balance()	剩余计算额度。一个额度可让一个标准工作区运行一分钟。
create_workspace(repo?, ref?, name?)	创建一个新工作区，可选择将代码仓库克隆到 $HOME/work。如果未提供名称，Reachpad 会生成显示名称。
list_workspaces()	列出你的工作区及各自的分叉数量
get_workspace(workspace)	查看工作区从何处启动：其头部快照、日志位置和分叉树
run_command(workspace, argv, cwd?, env?, timeout_ms?)	运行一条命令，并返回其退出代码和输出。暂停的工作区会恢复运行以处理请求。
checkpoint_workspace(workspace, name?)	从最近的已封存快照创建分叉；原工作区不会受到影响
expose_port(workspace, port, check?)	将端口开放到 Web，并获取可访问该端口的链接。对每个端口幂等。
list_ports(workspace)	列出此工作区开放的端口及其链接，按开放时间从早到晚排列
revoke_port(workspace, port)	关闭一个端口。之后重新开放时会生成一个不同的链接。
delete_workspace(workspace)	将工作区归档并释放方案名额。不会删除任何内容——快照和历史记录都会保留。

在 0.4.0 中更名。 过去有六个工具使用 *_environment 的名称，并接受 environment 参数，而 CLI、手册和仪表板都使用 workspace 一词。实际上始终只有一种对象；现在它也只有一种称呼。旧名称和旧参数仍然有效，但不会在文档中宣传，因此现有调用不会失效——不过请在新调用中使用 workspace 这一名称。

有意不提供： 在工作区内启动 Agent。这项功能已列入 reachpad 的路线图，但尚未加入服务集群——总是失败的工具会浪费模型的一轮调用，还会让模型不再信任其他工具，因此此服务不会宣传自己无法提供的功能。

端口链接是什么，不是什么

交给别人之前，值得先了解以下内容，因为这些信息无法从 URL 中看出：

• 任何已登录 Reachpad 且拥有链接的人都可以打开它。 这不是私人 URL，也不安全。请把它当作预览部署。
• 链接是地址，不是副本。 在同一端口重启应用，原链接就会提供新版本。
• 进程运行状态不会在暂停后保留。 工作区会冷启动，文件仍在，但没有任何进程运行。因此暂停后，链接会返回错误，直到该端口上再次有进程监听。访客的请求会唤醒暂停的工作区，但不会重启工作区内的任何进程。
• expose_port 随后会拨测该端口，并在没有响应时告知你，因为指向无人提供服务的端口的链接，看起来和可用链接一模一样。传入 check: false 可跳过拨测——拨测会恢复已暂停的工作区。
• 如果只有 REACHPAD_API_KEY，该密钥必须是 --role owner。 collaborator 密钥会被拒绝：列出端口会返回有效令牌，而令牌本身就是一种权限凭证。

它遵循的规则

以下说明了流式执行 API 的天真客户端会如何误导模型，以及本工具采取的不同做法。

• 未终止的流状态为 UNKNOWN，绝不算成功。 如果响应结束时没有终止事件，工具会明确这样说明。这不代表退出码为零，Agent 也不得据此重试非幂等命令。
• 它的截止时间比服务端宽松，因此服务端的响应总能赢得竞争。先放弃的客户端会把“你的构建已完成”变成“状态未知”，而这些数值会从服务端同步，而不是靠猜测。
• 拒绝会附带解决办法，而不是代码。 达到方案限额时，你会得到限额、当前计数和后续操作指引——这些数值来自服务端，因为客户端中硬编码的限额会在方案变更时立刻变成谎言。
• 结果是句柄，不是负载。 输出会以尾部内容的形式返回，并注明丢弃的字节数。构建日志可能有数 MB，而这么大的 MCP 结果会耗尽调用方的上下文窗口。
• 拒绝是结果，不是传输错误，因此模型可以读取并采取行动。只有未知的 工具 才是协议错误。

测试

node --test 'test/*.test.mjs'

无需网络和凭据。协议测试套件会将随附的服务端作为子进程启动，并通过标准输入输出与其进行真实的 JSON-RPC 通信；它还会在真实套接字上连接到一个模拟控制平面，因此被测内容没有任何内部导入。一个测试会针对真实的 reachpad 执行相同流程，并在未配置端点时跳过。

仓库

本仓库是源代码所在之处。它与 reachpad 后端刻意分开：这份代码是公开的，会发布到 npm，而且其发布工作流拥有发布权限——这些都不应放在与控制平面相同的仓库中。这里的任何内容都无法读取后端源代码，后端中的任何作业也不会将文件复制到这里。

src/client.js 中镜像了两个服务端常量——执行宽限期和默认执行超时时间。镜像常量通常会逐渐过时；但这个不会，因为后端自身的 CI 会获取已发布的这个包，并在两者不一致时失败。检查就在数值可能变更的地方。