base44-remote-dev

MCP 経由で Base44 アプリをリモート開発する

独自のコーディングエージェントを Base44 アプリのサンドボックスに接続し、 そこで直接開発できます。コマンドの実行、ファイルの読み取りや編集、grep、 ディレクトリの一覧表示などが可能です。サンドボックスは Base44 が提供し、 エージェントと LLM はお客様が用意します。

MCP 対応のクライアントであれば、どれでも動作します。例では Claude Code を使用します。

手軽に始める方法： Base44 アプリエディターで Send to Coding Agent をクリックします。ローカルエージェントの場合は、README を取得して MCP または base44 sandbox CLI（セクション 10）経由でサンドボックスを操作する、すぐに貼り付けられるプロンプトが表示されます。 ウェブの場合は、Base44 MCP コネクターを使う claude.ai チャットに貼り付けるプロンプトと、 Open Claude ボタンが表示されます。このボタンはエージェントを見つけるための入り口です。このスキルの残りの部分は リファレンスとしてご利用ください。

2 つの接続方式： ウェブエージェントは Base44 MCP コネクターを使って claude.ai に接続します（セクション 1～9）。これは通常の claude.ai チャットであり、独自のリポジトリベースのサンドボックスで動作する Claude Code on the web（claude.ai/code）ではない点にご注意ください。 ローカルエージェントは同じ MCP サーバーに接続することも、base44 sandbox CLI（Base44 CLI トークン、セクション 10）で サンドボックスを操作することもできます。ツール、動作、エラーコードは同じです。CLI では、より短いコマンド名（sandbox read、sandbox ls など）で 利用できるだけです。

---

1. MCP サーバーに接続する

Base44 MCP エンドポイントは次のとおりです。

https://app.base44.com/mcp

Claude Code に登録します（任意のフォルダーから実行できます）。

claude mcp add --transport http base44 https://app.base44.com/mcp

現在のフォルダーだけでなく、すべてのプロジェクトで利用できるようにする場合は、 --scope user を追加します。

claude mcp add は設定を書き込むだけで、認証はまだ行いません。

2. 認証する

Claude Code を起動し、MCP メニューを開きます。

claude

次に、Claude Code 内で次を実行します。

/mcp

base44 → Authenticate を選択します。ブラウザーが開き、Base44 OAuth フロー（PKCE）が始まります。ログインして承認してください。成功すると、/mcp に base44 が接続済みとして表示され、ツールの一覧が表示されます。

ブラウザーを開けない純粋な CLI／ヘッドレスクライアントでは、代わりに OAuth デバイス フロー（/oauth/device/code）を使用します。コードをリクエストし、別のデバイスのブラウザーで承認すると、 クライアントがトークンを受け取ります。

スコープ

ツール	必要なスコープ
read_file、grep、list_directory、list_user_apps	apps:read（デフォルトで付与）
write_file、edit_file、run_command、create_checkpoint	sandbox:write

sandbox:write はデフォルトでは付与されません。シェルやファイルの変更には、 明示的な許可が必要です。読み取りツールは動作するのに変更を伴うツールが NOT_AUTHORIZED を返す場合、トークンに sandbox:write がありません。再接続して サンドボックスへのアクセスを許可してください（デバイスフローでは明示的にリクエストできます）。

---

3. アプリを選び、状況を把握する

すべてのツールで appId が必須です。list_user_apps でアプリを確認し、 リクエストに ID を指定して、エージェントが呼び出しのたびに ID を渡すようにします。

何かを変更する前に、まず読み取り専用で全体像を把握します。

Using the base44 tools on appId <APP_ID>:
1. list_directory on the app root (recursive, depth 2)
2. read_file src/App.jsx and src/pages.config.js
3. grep for the component I want to change
Summarize the structure before editing.

コールドスタート： アプリでサンドボックスが実行されていない場合、最初のツール呼び出し時に 直近のコミットからサンドボックスが自動的に起動します。少し時間がかかりますが、 以降の呼び出しは高速です。

CLI のコマンド名： base44 sandbox CLI（セクション 10）では、これらの読み取りツールは次のように なります。list_directory → sandbox ls、read_file → sandbox read、 grep → sandbox grep。

---

4. 変更を加える

• edit_file（CLI では sandbox edit）— 既存ファイルの変更に推奨されます。正確な old_text→new_text の編集内容を指定します。replace_all を設定しない限り、各 old_text はファイル内で一意である必要があります。1 回の呼び出しでの編集はすべてアトミックに適用され（全件成功または全件失敗）、統合差分が返されます。書き込みを行わずに差分をプレビューするには、dry_run: true を渡します。
• write_file（CLI では sandbox write）— 新しいファイルの作成に使用します。既存ファイルを上書きするには、overwrite: true を渡す必要があります（暗黙的に上書きされることはありません）。
• run_command（CLI では sandbox run）— サンドボックスで任意の bash コマンドを実行します（ビルド、インストール、スキャフォールディング、コードモッド）。作業ディレクトリのデフォルトはアプリのルートです。呼び出しをまたいで cd は維持されないため、cwd パラメーターを使うか、コマンドを連結します（cd sub && cmd）。タイムアウトのデフォルトは 120s（最大 600s）で、出力は約 1 MB に制限されます。
• create_checkpoint（CLI では sandbox checkpoint）— ビルダーのバージョン履歴に復元ポイントを保存します。省略可能な name（メッセージ／タイトル）を指定できます。省略した場合は自動生成されます。何が変更されたかを簡潔にまとめると、ユーザーが適切なバージョンを選びやすくなります。保留中の変更はすべて先にフラッシュされ、コミットされるため、チェックポイントは最新のコードを基準とします。その後、チェックポイント ID、名前、git コミットハッシュが返されます。作業単位が完了したとき、また必ず停止する前に呼び出してください。チェックポイントされていない作業がロールバックされる可能性がある理由については、セクション 6 を参照してください。（最近の自動コミットがまだ永続化されたことを確認できない場合は、古い状態をチェックポイントする代わりに、再試行可能な COMMIT_FLUSH_PENDING を返して処理を拒否します。少し待ってから再試行してください。）

例：

On appId <APP_ID>, use edit_file to change the homepage heading in
src/pages/Home.jsx from "Welcome" to "Welcome back". Show me the diff first
with dry_run, then apply it.

---

5. プレビューと検証（編集 → 確認のループ）

ライブのログストリーミングツールはありませんが、フィードバックのループを回すことはできます。

• ライブで確認する： GET /api/apps/{app_id}/sandbox/preview-url を呼び出すと、開発サーバーが起動し、プレビュー URL が返されます。編集すると Vite HMR によって反映されます。409 は、アプリのコードを現在ビルドできないことを意味します。

• ビルドステータス： GET /api/apps/{app_id} は status.state として ready / processing / error を返します。

  どちらもプラットフォーム API の操作であり、サンドボックスツールではありません。MCP 経由では、execute_api を使って呼び出します。REST 経由で直接呼び出す場合は、個人用 API キーが必要です。 ワークスペース API キーは拒否されます。

• 必要に応じて run_command を使い、ビルド／型チェック／Lint のエラーを確認します：

  npm run build       # bundler/compile errors
  npx tsc --noEmit    # type errors
  npm run lint        # lint errors
  

• 開発サーバー（Vite）のログを読む： 管理対象の開発サーバーは /tmp/vite.log に書き込みます。run_command で末尾を表示すると、HMR／コンパイルエラーを確認できます：

  tail -c 32000 /tmp/vite.log
  

  （このファイルはアプリのツリーの外にあるため、ファイルツールではなく run_command からのみアクセスできます。そのため sandbox:write が必要です。）

確実なループは、edit_file → npm run build（または /tmp/vite.log の末尾を表示）→ エラーを修正 → プレビュー URL を開いて目視確認、です。

ブラウザー実行時エラー（コンパイルは成功するもののレンダリング時に例外をスローするコンポーネントや、失敗したクライアント API 呼び出し）は、/tmp/vite.log ではなくブラウザーのコンソールに表示されます。プレビュー URL を開いて確認してください。

---

6. 変更の永続化について

「保存」する必要はありません。変更を伴う呼び出しごとに、デバウンスされた自動コミット（約5秒）がスケジュールされます。変更はBase44のコードストレージにコミットおよびプッシュされるため、次のようになります。

• サンドボックスが終了しても変更が保持されます（サンドボックスは最後のコミットから再作成されます）。
• ビルダーの「Library」／「Data」タブに表示されます。
• バックエンド関数のデプロイとの整合性が保たれます。
• アプリの公開時に含まれます。

実際の運用上の注意点：

• 少しの間（約5秒）、変更が失われる可能性があります。最後の編集の直後にセッションを終了せず、コミットされるまで少し待ってください。
• コミットはチェックポイントではありません。 ビルダーのバージョン履歴に表示されるのはチェックポイントのみです。ユーザーが以前のバージョンで**「Restore」をクリックするか、ビルダーのメッセージで「Revert this」**をクリックすると、アプリのコードはそのチェックポイントのコミットまでロールバックされ、最後のチェックポイント以降に書き込まれた内容は、復元ポイントなしで破棄されます。作業の一区切りがついたとき、そして必ず終了前に、create_checkpoint（sandbox checkpoint）を呼び出してください。そうすれば、ユーザーが次に「Restore」を実行したとき、あなたの作業が消去されずに復元されます。
• エンティティ、エージェント、ワークフロー、バックエンド関数、ページルーティングへの編集は、コミット後にBase44へ自動的に同期されます。通常のページ／コンポーネント／CSSの編集はgitに保存されるため、追加の操作は必要ありません。

---

7. 同時実行：あなたとBase44ビルダー

あなたとアプリ内のBase44ビルダーは、同じアプリを同時に変更できません。

• **サンドボックスツールを使用中は、**Base44ビルダーのチャットがブロックされます（「An external agent is currently working on this app」）。セッションは暗黙的なもので、直近のツール呼び出しがセッションを構成し、短時間（約10分）操作がないと終了します。
• **Base44ビルダーがビルドの途中の場合、**変更を伴うツールはBUILDER_BUSYを返します。これを待機してから再試行する合図として扱ってください。先にビルドの状態を確認してから書き込むのは避けてください。確認と書き込みの間にビルダーが起動する可能性があるため、BUILDER_BUSYが返された後に再試行することで安全性が保たれます。読み取り専用ツールはビルド中も使用できます。

---

8. ガードレールと制限

• パスはアプリ内に限定されます。 ファイルツールはアプリのディレクトリ内でのみ動作し、ディレクトリ外への移動や絶対パスは拒否されます（PATH_OUTSIDE_SANDBOX）。
• ファイルツールでは.agents/を使用できません（PROTECTED_PATH）。ここにはエージェントが管理する設定とシークレット（.agents/.env）が含まれています。ファイルツールを使って読み取ったり編集したりしないでください。
• レート制限はアプリごとに適用されます。読み取りは約120回／分、変更は約60回／分、コマンドは約30回／分です。RATE_LIMITEDが返された場合は、処理を遅くしてください。
• delete_fileは専用ツールではありません。 run_command rmを使って削除してください。

表示される可能性のあるエラーコード

NOT_AUTHORIZED（スコープ／フラグが不足） · APP_NOT_FOUND（IDが間違っている、またはアクセス権がない） · PATH_OUTSIDE_SANDBOX · PROTECTED_PATH · NOT_FOUND · BINARY_FILE · EDIT_TEXT_NOT_FOUND · EDIT_TEXT_NOT_UNIQUE（old_textを一意にするか、replace_allを使用） · OVERWRITE_NOT_ALLOWED（overwrite: trueを指定） · TIMEOUT · OUTPUT_TRUNCATED · BUILDER_BUSY · COMMIT_FLUSH_PENDING（保留中の自動コミットはまだ永続化されていません。少し待ってから再試行してください。例：create_checkpoint） · RATE_LIMITED · BACKEND_ERROR。

メッセージはエージェントが自ら修正できるように書かれています。内容を読み、適宜対応してください。

---

9. ヒントとコツ

• 書き込む前に読みましょう。 手早く list_directory と read_file（または grep）を実行するだけで、手間はほとんどかからず、編集の精度が大幅に向上します。
• edit_file では dry_run を使いましょう。 変更を確定する前に差分を確認できます。特に複数の編集を行う場合に有効です。
• 既存のファイルには write_file より edit_file を使いましょう。 必要な箇所だけを編集できるため、既存の内容を上書きせず、レビューしやすい差分を作成できます。
• 大きなファイルでは、全体をコンテキストに読み込む代わりに、read_file の offset／limit を使って行範囲を読みましょう。
• 「壊れているように見える」ときは、推測する前に /tmp/vite.log の末尾を確認しましょう。 通常、問題があるファイルと行が正確に示されます。
• コミットを待ちましょう。 最後の編集後、切断または公開する前に数秒待って、自動コミットが完了するようにします。
• 毎回、作業をチェックポイントとして保存しましょう。 作業単位を終えたときと停止する前に、またリスクの高い編集に取りかかる前にも、create_checkpoint（sandbox checkpoint）を呼び出します。これにより、保留中の変更が先に反映されます。実行しないと、編集内容はコミットされてもバージョン履歴には表示されず、ビルダーで次に Restore または Revert を実行すると破棄されます（セクション 6）。
• 一度に実行するエージェントは 1 つだけにしましょう。 この機能は、アプリごとに 1 つの外部エージェントで使うよう設計されています。同じアプリに対して並行セッションを実行しないでください。

---

10. base44 sandbox CLI を使ったローカルエージェント

エージェントがマシン上で動作している場合は、OAuth ではなく Base44 CLI で認証し、CLI を通じて同じサンドボックスを操作できます。ツール、動作、エラーコード（セクション 8）は同じで、異なるのは利用方法と認証だけです。

認証。 Base44 CLI でログインします（base44 login）。base44 functions deploy で使うものと同じ認証情報を使用します。プロジェクト不要の base44 connectors コマンドと同様に、サンドボックスのサブコマンドは --app-id、次に BASE44_APP_ID、次にローカルの .app.jsonc からアプリ ID を解決します。config.jsonc は不要です。

コマンド名。 CLI では、各サンドボックスツールを短い名前で実行できます。

MCP ツール	CLI コマンド
list_directory	base44 sandbox ls
read_file	base44 sandbox read
write_file	base44 sandbox write
edit_file	base44 sandbox edit
run_command	base44 sandbox run
grep	base44 sandbox grep
create_checkpoint	base44 sandbox checkpoint

npx base44 sandbox read --app-id <APP_ID> src/App.jsx

base44 sandbox checkpoint では、任意の --name（メッセージ／タイトル）を指定して、復元ポイントを保存できます。作業単位を終えたときと停止する前に実行してください。CLI での書き込みはコミットされますが、チェックポイントには保存されません。ビルダーで Restore または Revert を実行すると、最後のチェックポイント以降の内容はすべて破棄されます（セクション 6）。

npx base44 sandbox checkpoint --app-id <APP_ID> --name "before refactor"

特定のアプリに関する完全なリファレンスをエージェントに渡す場合（手順書は公開されており、取得に認証は不要です）。

https://app.base44.com/api/sandbox/<APP_ID>/local-agent/readme.md

（クラウド／MCP での同等のものは .../api/sandbox/<APP_ID>/claude-web/readme.md です。）

このスキルのその他のすべての内容、つまり編集→プレビュー→検証のループ（セクション 5）、永続化（セクション 6）、並行処理（セクション 7）、ガードレール（セクション 8）も同様に適用されます。異なるのは利用方法と認証だけです。

---

11. コネクター（OAuth 連携）

サンドボックスのファイル／シェルツールに加えて、Base44 MCP サーバーには、アプリ上でサードパーティーの OAuth コネクター（Google Calendar、Gmail、Slack など）を管理するツールが 2 つあります。これらはサンドボックスのファイルシステムには触れず、アプリのコネクター状態を直接操作します。どちらも appId を指定します。

ツール	スコープ	目的
list_connectors	apps:read	アプリのコネクターを一覧表示します。integrationTypes を指定しない場合は、カタログ全体（名前、説明、接続済みかどうか、接続済みの場合はステータスと付与されたスコープ）を返します。特定のコネクターの詳細を確認するには、integrationTypes を指定します。
initiate_connector_connection	apps:write	コネクターを接続（またはスコープを再設定）します。入力：appId、integrationType、scopes、任意の connectionConfig。

次の 2 つの仕様を正しく理解してください。

• スコープは宣言型（マージではなく置き換え）。 initiate_connector_connection は、指定した scopes と完全に同じスコープをコネクターに設定します。省略したスコープは削除され、ユーザーに再度同意を求めます。必ず先に list_connectors を呼び出し、維持したい既存のスコープと新しいスコープをすべて含めたセットを渡してください。
• OAuth の完了には人間の操作が必要です。 ツールは already_authorized: true（対応不要）または、サインインして同意するためにユーザーがブラウザーで開く必要のある redirect_url を返します。自分で完了することはできません。ユーザーが完了したら、再度 list_connectors を呼び出して状態を確認し、付与されたスコープを読み取ってください（プロバイダーが要求より少ないスコープしか付与しない場合があります）。

必要な権限は apps:read／apps:write のみで、sandbox:write は不要です。CLI サーフェス（セクション 10）では、プロジェクトを指定しない base44 connectors コマンド（list-available、initiate --integration-type <t> --scopes <s...> --app-id <id>、pull）が同等の操作にあたり、同じ認証 URL を出力します。