reachpad-mcp

@reachpad/mcp

reachpad を使うと、Claude、Codex、その他のコーディングエージェントが、永続的なワークスペースでフルスタックアプリを構築し、別途デプロイすることなくリンクで共有できます。ワークスペースは、エージェントが自ら操作するクラウド開発用コンピューターです。リポジトリ、ファイルシステム、インストール済みの依存関係、ビルド状態がすべて呼び出しの間も保持されます。忘れてしまう一時的なサンドボックスではありません。プロセスは例外です。詳しくは以下をご覧ください。

これは MCP サーバーです。Claude、ChatGPT、Cursor、OpenCode、または独自のエージェントが、開発者がノートパソコンを開いたままにしておかなくても、ワークスペースを作成し、その中でコマンドを実行し、フォークして、後から再び利用できるようにします。

• 状態を保持します。 一時停止するとディスクが封印され、次の呼び出しではその封印から起動し、ファイル、インストール内容、git の状態がそのまま保たれます。再構築は不要です。プロセスは例外で、起動時は常にコールドブートです。
• フォークできます。 準備済みの状態から20回試行しても、費用がかかるのは差分ごとです。ワークスペースがマシンではなくスナップショットチェーンだからです。
• シークレットをワークスペースの外に保てます。 仲介された認証情報は、お客様に代わって境界で呼び出され、その値がワークスペース、ログ、ストアに入ることはありません。一方、ワークスペースに書き込まれた認証情報は、設計上、そこで読み取り可能です。
• エージェントを選びません。 REST API が正規のインターフェースで、このサーバー、SDK、CLI はその変換です。お好みのエージェントをご利用ください。

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

2つのトランスポート、1つの実装

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

stdio はローカルクライアントが使用し、Streamable HTTP はリモートコネクターが使用します。ツールも動作も同じです。分岐ではなく追加方式にしています。同じインターフェースに対する実装が2つあると、乖離していくためです。

HTTP 側は GET に対して405を返します。ここにあるすべてのツールはリクエスト／レスポンス方式であり、仕様では、到着しないトラフィックを待って接続を維持する代わりに、サーバー起点のストリームを拒否できます。セッションはありません。再起動で再構築できない情報が、呼び出しをまたいで保持されることはありません。また、独自の認証情報もありません。HTTP リクエストを認可するものが、そのまま reachpad も認可します。

デフォルトで認証が有効です。 REACHPAD_MCP_HTTP_TOKEN を設定すると、それがベアラートークンになります。何も設定しない場合は実行ごとにトークンが生成され、標準エラー出力に表示されます。背後で 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	ユーザーごとの認証情報です。1 つのアカウントを指定し、そのアカウントの権限でのみ操作できます。サーバーはリクエストからではなく、認証情報自体のレコードから ID を取得します。
REACHPAD_API_KEY	オプションの、ワークスペースごとにスコープが設定され、取り消し可能なキーです。設定すると、run_command はこのキーを使用し、ID の交換は不要です。
REACHPAD_MCP_HTTP_PORT	stdio の代わりに HTTP を提供します。
REACHPAD_MCP_HTTP_HOST	デフォルトは 127.0.0.1 です。このプロセスはお客様の認証情報を使ってコントロールプレーンに接続するため、インターネットに公開するアドレスにバインドする場合は、TLS を終端するプロキシの背後で意図的に行ってください。
REACHPAD_MCP_HTTP_TOKEN	ベアラートークンです。比較は定時間で行われます。指定されていない場合は、実行ごとに生成され、stderr に出力されます。指定がないからといって、エンドポイントが認証なしで公開されることはありません。
REACHPAD_MCP_HTTP_NO_AUTH	1 を指定すると、認証なしで提供されます。ポートに接続できるすべての呼び出し元に権限が付与されます。これは意図的な選択であり、デフォルトではありません。
REACHPAD_MCP_ALLOWED_ORIGINS	カンマ区切りで指定します。リストにない Origin を含むリクエストは拒否されます。ブラウザーはこれを偽装できないため、DNS リバインディングを防止できます。Origin がない場合はブラウザー以外のクライアントとして許可されます。

複数の認証情報が設定されている場合は、最も権限の狭いものが優先されます。また、拒否された認証情報を、より広い権限の認証情報で再試行することはありません。フォールバックすると、誰も選んでいない権限昇格が起きるためです。

ツール

ツール	機能
get_credit_balance()	残りのコンピューティングクレジットを取得します。クレジット 1 つで、標準ワークスペースを 1 分間実行できます。
create_workspace(repo?, ref?, name?)	新しいワークスペースを作成します。オプションでリポジトリを $HOME/work にクローンできます。名前を省略すると、Reachpad が表示名を生成します。
list_workspaces()	お客様のワークスペースと、それぞれのフォーク数を一覧表示します
get_workspace(workspace)	起動元の情報を取得します。ヘッドスナップショット、ログの位置、フォークツリーが含まれます
run_command(workspace, argv, cwd?, env?, timeout_ms?)	コマンドを 1 つ実行し、終了コードと出力を返します。一時停止中のワークスペースは、実行に応じて再開されます。
checkpoint_workspace(workspace, name?)	最後に確定したスナップショットからフォークします。元のワークスペースには変更を加えません
expose_port(workspace, port, check?)	ポートをウェブに公開し、アクセス用リンクを取得します。ポートごとに冪等です。
list_ports(workspace)	このワークスペースが公開しているポートを、古い順にリンクとともに一覧表示します
revoke_port(workspace, port)	ポートを 1 つ閉じます。後で再公開すると、別のリンクが発行されます。
delete_workspace(workspace)	ワークスペースをアーカイブしてプランの枠を解放します。何も削除されず、スナップショットと履歴は保持されます。

0.4.0 で名称を変更しました。 以前は 6 つのツール名が *_environment で、environment 引数を受け取っていましたが、CLI、マニュアル、ダッシュボードではすべて workspace と表記されていました。対象は最初から 1 つだけだったため、現在は表記も 1 つに統一しています。以前の名前と引数も引き続き機能し、案内には表示されません。そのため、すでにこれらを呼び出しているものに影響はありません。ただし、新しい呼び出しでは workspace の表記を使用してください。

意図的に含めていない機能： ワークスペース内でエージェントを起動する機能です。これは reachpad のロードマップにはありますが、まだフリートには含まれていません。必ず失敗するツールはモデルのターンを無駄にし、ほかの機能への信頼も損ないます。そのため、このサーバーは提供できない機能を案内しません。

ポートリンクとは何か、何ではないか

リンクを誰かに渡す前に、ぜひお読みください。URLからは次のことがわからないためです。

• Reachpad にサインインしている人なら誰でも、リンクを知っていれば開けます。 プライベートな URL でも、安全な URL でもありません。プレビュー用のデプロイと同じように扱ってください。
• リンクはアドレスであり、コピーではありません。 同じポートでアプリを再起動すると、同じリンクから新しいバージョンが表示されます。
• 実行中のプロセスは一時停止後も存続しません。 ワークスペースはファイルを保持したまま、何も実行されていない状態でコールドブートするため、一時停止後はそのポートで何かが再び待ち受けるまで、リンクはエラーを返します。訪問者のリクエストによって一時停止中のワークスペースは起動しますが、その中の何かが再起動するわけではありません。
• expose_port はその後にポートへ接続を試みます。何も応答しなかった場合に通知するためです。何も提供されていないポートへのリンクも、機能するリンクとまったく同じように見えてしまいます。接続を省略するには check: false を渡してください。接続を試みると、一時停止中のワークスペースが再開します。
• REACHPAD_API_KEY しかない場合、キーは --role owner でなければなりません。 collaborator キーは拒否されます。一覧表示で有効なトークンが返されるためです。トークンは権限そのものです。

これを支えるルール

ストリーミング実行 API の単純なクライアントがモデルを誤解させる要因と、この実装での対処方法を示します。

• 終了していないストリームは成功ではなく、UNKNOWN です。 終了イベントがないまま応答が終わると、ツールはその旨を明示します。終了コード 0 ではありません。エージェントは、その結果を根拠にして、べき等でないコマンドを再試行してはいけません。
• 期限はサーバー側より長く設定されています。そのため、サーバー側の応答が常に競争に勝ちます。クライアントが先に諦めると、「ビルドが完了しました」が「不明」に変わります。また、数値は推測ではなくサーバーから取得した値と一致します。
• 拒否時にはコードではなく、解決策が示されます。 プランの上限に達すると、上限、現在の件数、対処方法が返されます。数値はサーバーから取得します。クライアントに上限をハードコードすると、プランが変わった瞬間に虚偽になるためです。
• 結果はペイロードではなく、ハンドルです。 出力は末尾部分のみ返し、破棄したバイト数も明示します。ビルドログは数メガバイトになることがあり、そのサイズの MCP 結果は呼び出し元のコンテキストウィンドウを圧迫します。
• 拒否はトランスポートエラーではなく、結果です。そのため、モデルは内容を読んで対処できます。プロトコルエラーになるのは、ツール が不明な場合だけです。

テスト

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

ネットワークも認証情報も不要です。プロトコルテストスイートは、同梱のサーバーを子プロセスとして起動し、実際のソケット上にあるスタブのコントロールプレーンに対して、標準入出力経由で実際の JSON-RPC をやり取りします。そのため、テスト対象は内部インポートではありません。1 つのテストでは、実際の reachpad に対して同じ一連の処理を実行し、エンドポイントが設定されていない場合はスキップします。

リポジトリ

このリポジトリがソースです。reachpad のバックエンドとは意図的に分離しています。このコードは公開され、npm に公開され、そのリリースワークフローには公開権限があります。いずれも、コントロールプレーンと同じリポジトリに置くべきではありません。ここからバックエンドのソースを読むことはできず、バックエンドのジョブがファイルをこちらにコピーすることもありません。

サーバーの定数 2 つ、exec の猶予期間とデフォルトの exec タイムアウトは、src/client.js に複製されています。定数を複製すると通常は古くなりますが、これは古くなりません。バックエンド独自の CI が公開済みのこのパッケージを取得し、値が一致しない場合は失敗するためです。このチェックは、数値を変更する場所にあります。