Skip to main content
Glama

@reachpad/mcp

reachpad lets Claude, Codex and other coding agents build full-stack apps in persistent workspaces and share them by link, without a separate deployment. A workspace is a cloud development computer an agent operates itself: a repo, a filesystem, installed dependencies and build state that all survive between calls, not an ephemeral sandbox that forgets. Processes are the exception; see below.

This is the MCP server. It lets Claude, ChatGPT, Cursor, OpenCode or your own agent create a workspace, run commands in it, fork it, and come back to it later, without a developer keeping a laptop open for them.

  • It persists. Pause it and the disk is sealed; the next call boots from that seal with the files, installs and git state intact, rather than rebuilding. Processes are the exception: a start is always a cold boot.

  • It forks. Twenty attempts from one prepared state cost a delta each, not twenty rebuilds — because the workspace is a snapshot chain, not a machine.

  • It can keep secrets out of the workspace. A brokered credential is called at the boundary on your behalf and its value never enters the workspace, the log or the store. A credential written into the workspace instead is readable there, by design.

  • It is agent-agnostic. The REST API is canonical; this server, the SDK and the CLI are translations of it. Bring your own agent.

The API is the product boundary, not a web UI: reachpad.dev.

Install

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

In Claude Code:

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

Related MCP server: Uten Agent Terminal MCP

Two transports, one implementation

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

stdio is what a local client talks to; Streamable HTTP is what a remote connector talks to. Same tools, same behaviour — added rather than forked, because two implementations of one surface is how they drift.

The HTTP side answers 405 to GET: every tool here is request/response, and the spec permits declining the server-initiated stream rather than holding a connection open for traffic that never comes. There are no sessions — nothing is held across calls that a restart could not rebuild. And it carries no credential of its own: whatever authorizes the HTTP request is what authorizes reachpad.

It is authenticated by default. Set REACHPAD_MCP_HTTP_TOKEN and that is the bearer token; set nothing and one is generated for the run and printed on stderr, because a port that bridges to your account with run_command behind it should not be open to every other process on the machine:

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.

Serving with no authentication is still available and is now something you say out loud: REACHPAD_MCP_HTTP_NO_AUTH=1.

Configure

variable

meaning

REACHPAD_ENDPOINT

your reachpad host. Plaintext http:// to anything but loopback is refused before a socket opens.

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.

REACHPAD_API_KEY

optional, per-workspace scoped and revocable. When set, run_command uses it and needs no identity exchange.

REACHPAD_MCP_HTTP_PORT

serve HTTP instead of stdio.

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.

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.

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.

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.

If several credentials are set, the narrowest wins, and a refused credential is never retried under a broader one — falling back would be privilege escalation nobody chose to perform.

Tools

tool

what it does

get_credit_balance()

remaining compute credits. One credit runs one standard workspace for one minute.

create_workspace(repo?, ref?, name?)

a new workspace, optionally with a repository cloned into $HOME/work. Reachpad generates its display name when omitted.

list_workspaces()

your workspaces and how many forks each has

get_workspace(workspace)

what it boots from: its head snapshot, its log position and its fork tree

run_command(workspace, argv, cwd?, env?, timeout_ms?)

one command, its exit code and its output. A paused workspace resumes to serve it.

checkpoint_workspace(workspace, name?)

fork from the last sealed snapshot; the original is untouched

expose_port(workspace, port, check?)

open a port to the web and get the link that reaches it. Idempotent per port.

list_ports(workspace)

the ports this workspace has open, oldest first, with their links

revoke_port(workspace, port)

close one port. Re-opening it later mints a different link.

delete_workspace(workspace)

archive it and free the plan slot. Nothing is deleted — snapshots and history survive.

Renamed in 0.4.0. Six tools used to be spelled *_environment and took an environment argument, while the CLI, the manual and the dashboard all said workspace. There was only ever one object; now there is only one word for it. The old names and the old argument still work and are not advertised, so nothing that already calls them breaks — but write new calls against the workspace spelling.

Not here, deliberately: starting an agent inside the workspace. It is in reachpad's roadmap and not in the fleet yet — a tool that always fails costs a model a turn and teaches it to distrust the rest, so this server advertises nothing it cannot serve.

Worth reading before you hand one to somebody, because none of it is discoverable from the URL:

  • Anyone signed in to Reachpad who has the link can open it. It is not a private URL and not a secure one. Treat it like a preview deployment.

  • The link is an address, not a copy. Restart the app on the same port and the same link serves the new version.

  • A running process does not survive a pause. The workspace cold-boots with its files intact and nothing running, so after a pause the link answers with an error until something is listening on that port again. A visitor's request wakes a paused workspace; it does not restart anything inside it.

  • expose_port dials the port afterwards and tells you if nothing answered, because a link to a port nothing is serving looks exactly like a link that works. Pass check: false to skip it — the dial resumes a paused workspace.

  • With only REACHPAD_API_KEY, the key must be --role owner. A collaborator key is refused: listing hands back live tokens, and a token is a capability.

The rules it is built to

These are the ways a naive client of a streaming exec API misleads a model, and what this one does instead.

  • An unterminated stream is UNKNOWN, never success. If the response ends without a terminal event, the tool says so in those words. It is not a zero exit, and an agent must not retry a non-idempotent command on the strength of it.

  • Its deadline is looser than the server's, so a server-side answer always wins the race. A client that gives up first turns "your build finished" into "unknown", and the numbers are mirrored from the server rather than guessed.

  • Refusals carry remedies, not codes. At your plan limit you get the limit, your current count, and what to do — the numbers come from the server, because a limit hardcoded in a client is a lie the moment your plan changes.

  • Results are handles, not payloads. Output is tailed with the dropped byte count named. Build logs can be megabytes, and an MCP result that size destroys the caller's context window.

  • A refusal is a result, not a transport error, so the model can read it and act. Only an unknown tool is a protocol error.

Test

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

No network and no credentials. The protocol suite spawns the shipped server as a child process and speaks real JSON-RPC over its stdio against a stub control plane on a real socket, so nothing under test is an internal import. One test runs the same arc against a real reachpad and skips when no endpoint is configured.

Repository

This repository is the source. It is deliberately separate from the reachpad backend: this code is public, it is published to npm, and its release workflow holds publishing rights — none of which belong in the same repository as the control plane. Nothing here can read the backend's source, and no job in the backend copies files out to here.

Two server constants are mirrored in src/client.js — the exec grace period and the default exec timeout. A mirrored constant normally rots; this one does not, because the backend's own CI fetches this published package and fails if they disagree. The check lives where the number would change.

Available Tools

7 tools
checkpoint_environmentFork environmentAInspect

Fork an environment from its last sealed snapshot into a new one. The original is untouched. This is how you try several approaches from one prepared state — the fork costs a delta, not a rebuild.

Inputs: environment (required), name.

create_environmentCreate environmentAInspect

Create a persistent development environment: a filesystem and processes that survive between calls. Optionally clone a git repository into it. Returns the environment id used by every other tool.

Inputs: ref, name, repo.

delete_environmentArchive environmentA
DestructiveIdempotent
Inspect

Archive an environment, freeing the plan slot it holds. Nothing is deleted: its snapshots and history survive, it simply stops counting as live and can no longer be used.

Inputs: environment (required).

get_credit_balanceGet compute-credit balanceA
Read-onlyIdempotent
Inspect

Show this account's remaining compute credits. One credit runs one standard environment for one minute; paused environments use no compute credits.

Inputs: no named parameters.

get_environmentInspect environmentA
Read-onlyIdempotent
Inspect

What an environment resumes from: its head snapshot, how far its log had got, and its fork tree. Every start is a cold boot from the head snapshot: files survive, running processes do not.

Inputs: environment (required).

list_environmentsList environmentsA
Read-onlyIdempotent
Inspect

List this account's environments, with how many forks each has.

Inputs: no named parameters.

run_commandRun a commandA
Destructive
Inspect

Run one command in an environment and get its exit code and output. Not a shell: pass argv as a list, and ask for a shell explicitly with ["/bin/sh","-lc","…"] if you want one. A paused environment resumes to serve this.

Inputs: argv (required), environment (required), cwd, env, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool addresses a distinct concern: credit balance, environment lifecycle, and command execution are cleanly separated. Even checkpoint_environment is unambiguous because it explicitly forks an environment into a new one.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case, such as create_environment, list_environments, and delete_environment. Singular/plural usage is natural and predictable.

    Tool Count5/5

    Seven tools is well-scoped for managing persistent development environments: credit checking, creation, listing, inspection, command execution, forking, and deletion/archival. No tool feels redundant or out of place.

    Completeness5/5

    The environment lifecycle is covered end-to-end: create, read (list/get), fork/checkpoint, execute commands, and delete/archive. The credit balance tool fills the one supporting need for running environments, leaving no obvious dead ends.

    Maintenance

    ActivityStale
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers