{
  "markdown": "# @reachpad/mcp\n\nreachpad lets Claude, Codex and other coding agents build full-stack apps in\npersistent workspaces and share them by link, without a separate deployment. A\nworkspace is a cloud development computer an agent operates itself: a repo, a\nfilesystem, installed dependencies and build state that all survive between\ncalls, not an ephemeral sandbox that forgets. Processes are the exception; see\nbelow.\n\nThis is the MCP server. It lets Claude, ChatGPT, Cursor, OpenCode or your own\nagent create a workspace, run commands in it, fork it, and come back to it\nlater, without a developer keeping a laptop open for them.\n\n- **It persists.** Pause it and the disk is sealed; the next call boots from\n  that seal with the files, installs and git state intact, rather than\n  rebuilding. Processes are the exception: a start is always a cold boot.\n- **It forks.** Twenty attempts from one prepared state cost a delta each, not\n  twenty rebuilds — because the workspace is a snapshot chain, not a machine.\n- **It can keep secrets out of the workspace.** A brokered credential is called at\n  the boundary on your behalf and its value never enters the workspace, the\n  log or the store. A credential written into the workspace instead is\n  readable there, by design.\n- **It is agent-agnostic.** The REST API is canonical; this server, the SDK and\n  the CLI are translations of it. Bring your own agent.\n\nThe API is the product boundary, not a web UI: [reachpad.dev](https://reachpad.dev).\n\n## Install\n\n```sh\nnpx -y @reachpad/mcp          # stdio, for a local client\n```\n\nIn Claude Code:\n\n```sh\nclaude mcp add reachpad -e REACHPAD_IDENTITY_CREDENTIAL=… -- npx -y @reachpad/mcp\n```\n\n## Two transports, one implementation\n\n```sh\nnpx @reachpad/mcp                                  # stdio\nREACHPAD_MCP_HTTP_PORT=8722 npx @reachpad/mcp      # streamable http\n```\n\nstdio is what a local client talks to; Streamable HTTP is what a remote\nconnector talks to. Same tools, same behaviour — added rather than forked,\nbecause two implementations of one surface is how they drift.\n\nThe HTTP side answers **405 to `GET`**: every tool here is request/response, and\nthe spec permits declining the server-initiated stream rather than holding a\nconnection open for traffic that never comes. There are **no sessions** —\nnothing is held across calls that a restart could not rebuild. And it carries\n**no credential of its own**: whatever authorizes the HTTP request is what\nauthorizes reachpad.\n\nIt is **authenticated by default**. Set `REACHPAD_MCP_HTTP_TOKEN` and that is\nthe bearer token; set nothing and one is generated for the run and printed on\nstderr, because a port that bridges to your account with `run_command` behind\nit should not be open to every other process on the machine:\n\n```\nreachpad mcp: streamable http on http://127.0.0.1:8722\nreachpad mcp: no REACHPAD_MCP_HTTP_TOKEN was set, so this one was generated for this run:\n\n    Authorization: Bearer 3Qk…\n\nreachpad mcp: it changes every restart. Set REACHPAD_MCP_HTTP_TOKEN to pin it, or\nreachpad mcp: REACHPAD_MCP_HTTP_NO_AUTH=1 to serve with no authentication at all.\n```\n\nServing with no authentication is still available and is now something you say\nout loud: `REACHPAD_MCP_HTTP_NO_AUTH=1`.\n\n## Configure\n\n| variable | meaning |\n|---|---|\n| `REACHPAD_ENDPOINT` | your reachpad host. Plaintext `http://` to anything but loopback is refused before a socket opens. |\n| `REACHPAD_IDENTITY_CREDENTIAL` | your per-user credential. It names one account and can act for no other — the server takes the identity from the credential's own record, never from the request. |\n| `REACHPAD_API_KEY` | optional, per-workspace scoped and revocable. When set, `run_command` uses it and needs no identity exchange. |\n| `REACHPAD_MCP_HTTP_PORT` | serve HTTP instead of stdio. |\n| `REACHPAD_MCP_HTTP_HOST` | default `127.0.0.1`. This process bridges to a control plane with your credentials, so binding it to the world is a decision made on purpose, behind a proxy that terminates TLS. |\n| `REACHPAD_MCP_HTTP_TOKEN` | bearer token, compared in constant time. Absent, one is **generated for the run and printed on stderr** — the endpoint is never unauthenticated by omission. |\n| `REACHPAD_MCP_HTTP_NO_AUTH` | `1` serves with no authentication at all: **every caller that can reach the port is authorized**. An affirmative choice, not a default. |\n| `REACHPAD_MCP_ALLOWED_ORIGINS` | comma-separated. A request carrying an unlisted `Origin` is refused — a browser cannot forge it, which closes DNS rebinding. No `Origin` at all is a non-browser client and is allowed. |\n\nIf several credentials are set, the narrowest wins, and **a refused credential\nis never retried under a broader one** — falling back would be privilege\nescalation nobody chose to perform.\n\n## Tools\n\n| tool | what it does |\n|---|---|\n| `get_credit_balance()` | remaining compute credits. One credit runs one standard workspace for one minute. |\n| `create_workspace(repo?, ref?, name?)` | a new workspace, optionally with a repository cloned into `$HOME/work`. Reachpad generates its display name when omitted. |\n| `list_workspaces()` | your workspaces and how many forks each has |\n| `get_workspace(workspace)` | what it boots from: its head snapshot, its log position and its fork tree |\n| `run_command(workspace, argv, cwd?, env?, timeout_ms?)` | one command, its exit code and its output. A paused workspace resumes to serve it. |\n| `checkpoint_workspace(workspace, name?)` | fork from the last sealed snapshot; the original is untouched |\n| `expose_port(workspace, port, check?)` | open a port to the web and get the link that reaches it. Idempotent per port. |\n| `list_ports(workspace)` | the ports this workspace has open, oldest first, with their links |\n| `revoke_port(workspace, port)` | close one port. Re-opening it later mints a **different** link. |\n| `delete_workspace(workspace)` | archive it and free the plan slot. Nothing is deleted — snapshots and history survive. |\n\n**Renamed in 0.4.0.** Six tools used to be spelled `*_environment` and took an\n`environment` argument, while the CLI, the manual and the dashboard all said\nworkspace. There was only ever one object; now there is only one word for it.\nThe old names and the old argument still work and are not advertised, so\nnothing that already calls them breaks — but write new calls against the\nworkspace spelling.\n\n**Not here, deliberately:** starting an agent inside the workspace. It is in\nreachpad's roadmap and not in the fleet yet — a tool that always fails costs a\nmodel a turn and teaches it to distrust the rest, so this server advertises\nnothing it cannot serve.\n\n### What a port link is, and is not\n\nWorth reading before you hand one to somebody, because none of it is\ndiscoverable from the URL:\n\n- **Anyone signed in to Reachpad who has the link can open it.** It is not a\n  private URL and not a secure one. Treat it like a preview deployment.\n- **The link is an address, not a copy.** Restart the app on the same port and\n  the same link serves the new version.\n- **A running process does not survive a pause.** The workspace cold-boots\n  with its files intact and nothing running, so after a pause the link answers\n  with an error until something is listening on that port again. A visitor's\n  request wakes a paused workspace; it does not restart anything inside it.\n- **`expose_port` dials the port afterwards** and tells you if nothing\n  answered, because a link to a port nothing is serving looks exactly like a\n  link that works. Pass `check: false` to skip it — the dial resumes a paused\n  workspace.\n- **With only `REACHPAD_API_KEY`, the key must be `--role owner`.** A\n  `collaborator` key is refused: listing hands back live tokens, and a token is\n  a capability.\n\n## The rules it is built to\n\nThese are the ways a naive client of a streaming exec API misleads a model, and\nwhat this one does instead.\n\n- **An unterminated stream is UNKNOWN, never success.** If the response ends\n  without a terminal event, the tool says so in those words. It is not a zero\n  exit, and an agent must not retry a non-idempotent command on the strength of\n  it.\n- **Its deadline is looser than the server's**, so a server-side answer always\n  wins the race. A client that gives up first turns \"your build finished\" into\n  \"unknown\", and the numbers are mirrored from the server rather than guessed.\n- **Refusals carry remedies, not codes.** At your plan limit you get the limit,\n  your current count, and what to do — the numbers come from the server, because\n  a limit hardcoded in a client is a lie the moment your plan changes.\n- **Results are handles, not payloads.** Output is tailed with the dropped byte\n  count named. Build logs can be megabytes, and an MCP result that size destroys\n  the caller's context window.\n- **A refusal is a result, not a transport error**, so the model can read it and\n  act. Only an unknown *tool* is a protocol error.\n\n## Test\n\n```sh\nnode --test 'test/*.test.mjs'\n```\n\nNo network and no credentials. The protocol suite spawns the shipped server as\na child process and speaks real JSON-RPC over its stdio against a stub control\nplane on a real socket, so nothing under test is an internal import. One test\nruns the same arc against a real reachpad and skips when no endpoint is\nconfigured.\n\n## Repository\n\nThis repository is the source. It is deliberately **separate from the reachpad\nbackend**: this code is public, it is published to npm, and its release\nworkflow holds publishing rights — none of which belong in the same repository\nas the control plane. Nothing here can read the backend's source, and no job in\nthe backend copies files out to here.\n\nTwo server constants are mirrored in `src/client.js` — the exec grace period\nand the default exec timeout. A mirrored constant normally rots; this one does\nnot, because the backend's own CI fetches this published package and fails if\nthey disagree. The check lives where the number would change.\n",
  "bytes": 9962,
  "sha": "5c4becbbe8298e937842cef4138132d7dae65bebe300eb5667eabec25825a832",
  "repo_slug": "reachpad/reachpad-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_reachpad_reachpad_mcp_ee6ffd4a/readme"
}