Superserve Sandbox MCP

公式

Superserveがホストするエージェント向けのセキュアな仮想マシン

superserve.ai で表示

Superserve Sandbox MCPで何ができますか？

サンドボックスの作成と実行 — アシスタントにサンドボックスを起動させ、sandbox_create と sandbox_exec を使って python --version のようなコマンドを実行させます。
サンドボックス内のファイル管理 — アシスタントに sandbox_files_read、sandbox_files_write、sandbox_files_list を使ってサンドボックス内のファイルの読み取り、書き込み、一覧表示をさせます。
ネットワークアクセスの制御 — sandbox_create または sandbox_update で egress ルールを設定し、送信先を許可またはブロックしてから、sandbox_network_log でトラフィックを監査します。
プレビュー URL の公開 — アシスタントに sandbox_preview_url を呼び出して実行中のサービスを公開させ、公開リンクまたは期限付きのプライベートリンクを取得します。
GUI デスクトップの操作 — sandbox_computer を使って、デスクトップサンドボックス内でスクリーンショット、クリック、タイピング、スクロールを行い、ブラウザ自動化タスクを実行します。
サンドボックスのライフサイクル管理 — sandbox_pause、sandbox_resume、sandbox_kill でサンドボックスを一時停止、再開、または完全に削除します。

ドキュメント

MCPサーバー

任意のMCPクライアントからSuperserveサンドボックスを作成、実行、管理します。

エージェント自身にサンドボックスを作成させたいですか？このMCPサーバーがそれを実現します。

Superserve MCPサーバー（@superserve/mcp）は、サンドボックスのプリミティブをModel Context Protocolツールとして公開します。これにより、MCP対応クライアント（Claude、Cursor、VS Code、Windsurf、Codex）は、隔離されたFirecrackerマイクロVM内でサンドボックスの作成、コマンドの実行、ファイルの読み書き、テンプレートの構築、シークレットの仲介、ネットワークアクセスの制御ができます。

実行方法は2つあります：npxを介したローカル（stdio経由）、またはローカルインストール不要のホステッドエンドポイント（https://mcp.superserve.ai）です。どちらもSUPERSERVE_API_KEYで認証し、呼び出しごとにIDでサンドボックスを指定します。TypeScript SDKの薄いラッパーであるため、サンドボックスごとのデータプレーントークンがモデルに届くことはありません。

クイックスタート

サーバーをクライアントに追加し（インストールを参照）、エージェントに*「サンドボックスを作成して、その中でpython --versionを実行して」*と依頼します。エージェントはsandbox_createを呼び出し、次にsandbox_execを呼び出して、結果を報告します。コードは不要です。

Superserve APIキーが必要です。APIキーページで作成できます。グローバルインストールはありません。npxが初回使用時にサーバーを取得します。

インストール

注記

サーバーのenvにSUPERSERVE_API_KEYを設定してください。MCPクライアントはシェルからそれを継承しません。クライアントが対応している場合は、生のキーを貼り付けるのではなく、シークレット入力プロンプトを優先してください（下記のVS Codeを参照）。

```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}} claude mcp add superserve \ --env SUPERSERVE_API_KEY=ss_live_xxxxxxxxxxxxxxxx \ -- npx -y @superserve/mcp ``` `claude_desktop_config.json`に追加（macOS：`~/Library/Application Support/Claude/`）：

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

`.cursor/mcp.json`（プロジェクト）または`~/.cursor/mcp.json`（グローバル）に追加：

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

`.vscode/mcp.json`に追加。`inputs`ブロックは、キーを平文で保存する代わりにプロンプトで入力させます：

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "inputs": [
    {
      "id": "superserve-key",
      "type": "promptString",
      "description": "Superserve API key",
      "password": true
    }
  ],
  "servers": {
    "superserve": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "${input:superserve-key}" }
    }
  }
}
```

`~/.codeium/windsurf/mcp_config.json`に追加：

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

`~/.codex/config.toml`に追加。`env_vars`は環境から`SUPERSERVE_API_KEY`を転送するため、生のキーは設定ファイルに保存されません（先にシェルでエクスポートしてください）。Codexはまた、クロスツールのワークフローガイダンスのためにサーバーの`instructions`を読み取ります。

```toml theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
[mcp_servers.superserve]
command = "npx"
args = ["-y", "@superserve/mcp"]
env_vars = ["SUPERSERVE_API_KEY"]
```

[ホステッド](#hosted-remote)エンドポイントの場合は、`bearer_token_env_var = "SUPERSERVE_API_KEY"`を指定して`url = "https://mcp.superserve.ai"`を使用します。

ホステッド（リモート）

ローカルで何も実行したくないですか？ https://mcp.superserve.aiのホステッドエンドポイントはStreamable HTTPを話します。npxもNodeも不要です。Superserve APIキーをベアラートークンとして送信します。エンドポイントはステートレスでアカウントスコープです（キーはすでにチームにマッピングされています）。サンドボックスごとのデータプレーントークンがサーバーから出ることはありません。

注記

ベアラー認証は、リクエストヘッダーを設定できる任意のクライアントで機能します。Claude Code、Cursor、VS Code、Anthropic Messages APIコネクタなどです。Claude.ai、 Claude DesktopのカスタムコネクタUI、ChatGPT開発者モードには静的ベアラー/カスタムヘッダーフィールドがありません（OAuthを想定）。ホステッドエンドポイントはまだOAuthをサポートしていないため、そこではローカルインストールを使用してください。

```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}} claude mcp add --transport http superserve https://mcp.superserve.ai \ --header "Authorization: Bearer ss_live_xxxxxxxxxxxxxxxx" ``` `.cursor/mcp.json`（プロジェクト）または`~/.cursor/mcp.json`（グローバル）に追加：

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "url": "https://mcp.superserve.ai",
      "headers": { "Authorization": "Bearer ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```

`.vscode/mcp.json`に追加。`inputs`ブロックは、キーを平文で保存する代わりにプロンプトで入力させます：

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "inputs": [
    {
      "id": "superserve-key",
      "type": "promptString",
      "description": "Superserve API key",
      "password": true
    }
  ],
  "servers": {
    "superserve": {
      "type": "http",
      "url": "https://mcp.superserve.ai",
      "headers": { "Authorization": "Bearer ${input:superserve-key}" }
    }
  }
}
```

[Anthropic Messages API](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector)リクエストでコネクタとして渡します：

```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcp_servers": [
    {
      "type": "url",
      "name": "superserve",
      "url": "https://mcp.superserve.ai",
      "authorization_token": "ss_live_xxxxxxxxxxxxxxxx"
    }
  ]
}
```

ローカルサーバーと同じツールと動作です。唯一の違いはトランスポートと、キーがenv変数ではなくベアラーヘッダーとして送信されることです。

ツール

ツール	機能
`sandbox_create`	新しいサンドボックスを作成し、その`id`を返します。`secrets`、egressルール、`preview_access`を受け付けます。
`sandbox_update`	メタデータ、egressルール、ライフサイクルウィンドウ、または`preview_access`を変更します。
`sandbox_list`	サンドボックス（アクティブおよび一時停止）を一覧表示し、メタデータでフィルタリングできます。
`sandbox_info`	1つのサンドボックスのステータス、リソース、メタデータ、ネットワークルール、シークレットバインディングを取得します。読み取り専用。
`sandbox_exec`	シェルコマンドを実行し、stdout、stderr、終了コードを返します。一時停止中のサンドボックスを自動再開します。
`sandbox_files_read`	ファイルを読み取ります（UTF-8テキスト、バイナリの場合はbase64）。
`sandbox_files_write`	ファイルを作成または上書きします。親ディレクトリは自動的に作成されます。
`sandbox_files_list`	ディレクトリのエントリを一覧表示します（名前、タイプ、サイズ、変更時刻）。
`sandbox_files_download_dir`	ディレクトリをbase64 ZIPとしてダウンロードします（シンボリックリンクはスキップ）。10 MiBで上限。それ以上はSDK/CLIを使用。
`sandbox_pause`	サンドボックスを一時停止します。状態は保持されます。
`sandbox_resume`	一時停止中のサンドボックスを再開します（通常は不要。execが自動再開します）。
`sandbox_kill`	サンドボックスを完全に削除します。
`sandbox_preview_url`	ポートを公開し、クリーンな公開URLまたは期限付きの非公開署名付きURLを返します。
`sandbox_network_log`	再開せずにサンドボックスの送信接続（ホスト、判定、バイト数）を監査します。
`sandbox_computer`	GUIデスクトップサンドボックスを操作します：スクリーンショット、マウス、キーボード、スクロール、リサイズ、ビューアーURL。1回の呼び出しで1アクション。
`sandbox_template_list`	チームが起動できるテンプレート（ベースイメージ）を一覧表示します。
`sandbox_template_create`	特定のvCPU/メモリ/ディスク形状またはプリインストールされたソフトウェアでカスタムテンプレートを構築します（非同期。準備完了をポーリング）。
`secret_list`	バインド可能なチームシークレットを一覧表示します（メタデータのみ。値は決して表示されません）。
`sandbox_attach_secret`	保存されたシークレットを実行中のサンドボックスに環境変数としてバインドします。
`sandbox_detach_secret`	サンドボックスからシークレットバインディングを削除します。

ほとんどのツールはsandbox_idを受け取ります。例外はsandbox_create、sandbox_list、sandbox_template_list、sandbox_template_create、secret_listです。これらのいずれかから始めてIDを取得し、後続の呼び出しに渡します。読み取り専用ツール（sandbox_list、sandbox_info、sandbox_files_read、sandbox_files_list、sandbox_files_download_dir、sandbox_network_log、sandbox_template_list、secret_list）は注釈が付けられており、クライアントは確認プロンプトをスキップできます。sandbox_preview_urlは要求されたポートを公開するため冪等な書き込みであり、sandbox_killは破壊的と注釈されています。

例

*「サンドボックスを起動して、最初の素数を出力するPythonスクリプトを書き、それを実行して」*という典型的なエージェントフロー：

sandbox_create       { name: "primes" }
                       → { id: "a1b2c3…", name: "primes", status: "active" }

sandbox_files_write  { sandbox_id: "a1b2c3…", path: "/app/primes.py", content: "…" }
                       → { path: "/app/primes.py", bytes: 142 }

sandbox_exec         { sandbox_id: "a1b2c3…", command: "python /app/primes.py" }
                       → { exit_code: 0, stdout: "2 3 5 7 11 13 17 19 23 29", stderr: "" }

完了したら、エージェントはsandbox_pause（状態保持、維持コスト削減）またはsandbox_kill（完全削除）を実行できます。

設定

変数	必須	説明
`SUPERSERVE_API_KEY`	はい	Superserve APIキー（`ss_live_`で始まります）。
`SUPERSERVE_BASE_URL`	いいえ	コントロールプレーンURLを上書きします（デフォルトは`https://api.superserve.ai`）。

動作と制限

自動再開。 sandbox_execとファイルツールは一時停止中のサンドボックスを透過的に再開するため、エージェントが先にsandbox_resumeを呼び出す必要はありません。sandbox_resumeはサンドボックスを明示的にウォームアップするためだけに存在します。
コンテキスト用に出力が制限されます。 sandbox_execはstdoutとstderrをそれぞれ32 KiBに切り詰めます。切り詰められた結果はtruncated: trueを設定し、元のバイト長を報告します。sandbox_files_readは1 MiBを超えるファイルを拒否します（部分的なコンテンツは返しません）。エラーはsandbox_execでスライスを読むか（例：head -c）、SDK/CLIでファイル全体をダウンロードするよう指示します。sandbox_files_writeのインラインコンテンツは8 MiBで上限です。
デフォルトのコマンドタイムアウトは60秒で、上限は10分です。呼び出しごとにtimeout_msで上書きできます。
Egressは制御可能です。 allow_out（ドメインパターン、IP、またはCIDR）は許可された宛先を追加します。deny_out（IPまたはCIDR、ドメインなし）はそれらをブロックします。allow_outだけではサンドボックスをロックダウンしません。厳格な許可リストの場合は、deny_out: ["0.0.0.0/0"]（すべて拒否してから、リストされた宛先を許可）と組み合わせてください。許可リストにドメインルールがある場合、またはワークロードがホスト名を解決する場合は、サンドボックスのDNSリゾルバー（1.1.1.1/32と8.8.8.8/32）も許可してください。すべて拒否はDNSもブロックするためです。IPのみの許可リストではこれらを除外してください。許可されたリゾルバーは追加の送信チャネルにすぎません。これらはsandbox_createまたはsandbox_updateで設定し、サンドボックスが実際に到達したものをsandbox_network_logで監査します。
エラーは実用的です。 失敗したツール呼び出しは、生のスタックトレースではなく、エージェントに次に何をすべきかを伝える短いメッセージを返します。例：「サンドボックスクォータに達しました。サンドボックスを一時停止または削除するか、後で再試行してください。」 — これによりエージェントは自己修正できます。

シークレット、テンプレート、ポート

シークレット。 資格情報を平文のenv_varsとして渡さないでください。代わりに：

TypeScript SDK（Secret.create()）またはコンソールでシークレットを一度作成します。生の値がエージェントやMCPサーバーを通過することはないため、シークレットの作成は意図的にMCPツールではありません。
secret_listでバインド可能なシークレットを発見します（メタデータのみ。値がプラットフォームから出ることはありません）。
作成時にバインドします（sandbox_createのsecrets: { ANTHROPIC_API_KEY: "anthropic-prod" }）、または後でsandbox_attach_secret / sandbox_detach_secretでバインドします。

サンドボックスはプロキシトークンを認識します。プラットフォームは、シークレットの許可されたホストへの送信リクエストに対してのみ、実際の資格情報を交換します。

テンプレート。 サンドボックスはテンプレートからvCPU/メモリ/ディスクを継承し、sandbox_create時にそれらを上書きできません。特定の形状（たとえば4 vCPUサンドボックス）やプリインストールされたソフトウェアが必要な場合は、sandbox_template_createでテンプレートを構築し、sandbox_template_listをポーリングしてstatusがreadyになるまで待ってから、from_templateとして渡します。

ポート。 新しいMCPサンドボックスは、新しく公開されたポートのデフォルトアクセスとしてpublicを使用します。明示的に公開されたポートのみが到達可能です。sandbox_create（またはsandbox_update）にpreview_access: "private"を渡すと、将来のポートのデフォルトが変更されます。既存のポートは独自のモードを保持します。sandbox_execでサーバーを起動し、sandbox_preview_urlを呼び出します。このツールはその1つのポートを冪等的に公開し、返されたポートモードを使用して、クリーンな公開URLまたは期限付きの非公開署名付きURLを返します。非公開リンクのデフォルトは1時間です。expires_in_secondsを1〜604800秒の値に設定します。プレビューURLを参照してください。

コンピューター使用

sandbox_computerは、superserve/desktopなどのデスクトップテンプレートから作成されたサンドボックス内のGUIデスクトップを操作します。コンピューター使用モデルが出力する語彙のactionを1回の呼び出しにつき1つ受け取ります：screenshot、left_click、right_click、middle_click、double_click、triple_click、left_click_drag、left_mouse_down、left_mouse_up、mouse_move、key、type、scroll、wait、resize、stream_url。ポインターアクションは画面ピクセル（原点は左上）でcoordinate: [x, y]を受け取ります。keyとtypeはtextを受け取ります。scrollはscroll_directionとオプションのscroll_amountを受け取ります。

sandbox_create    { name: "browser", from_template: "superserve/desktop" }
sandbox_computer  { sandbox_id: "a1b2c3…", action: "left_click", coordinate: [640, 32] }
                    → text "left_click done (1280x800)" + image/png
sandbox_computer  { sandbox_id: "a1b2c3…", action: "type", text: "https://example.com" }
sandbox_computer  { sandbox_id: "a1b2c3…", action: "key", text: "Return" }

入力アクションは結果の新しいスクリーンショットを返すため、モデルのアクション→確認のターンは1回のツール呼び出しです。連続して複数のアクションを送信する場合はscreenshot_after: falseを渡します。waitはサンドボックスへのリクエストなしでduration_ms（上限10秒）待機します。stream_urlはサンドボックスのプレビューポリシーに基づいて、デスクトップ用のライブブラウザービューアーを返します。

入力アクションが失敗した場合、入力はすでに配信されている可能性があります。ツールはその旨を伝え、繰り返す前にスクリーンショットを撮るようエージェントに求めます。基盤となるSDKサーフェスについてはデスクトップガイドを参照してください。

MCPサーフェスにまだないもの

MCPサーバーは一般的なエージェントループをカバーしており、上記の表が完全なv1ツールセットです。いくつかのSDK機能はまだ公開されていません。以下の用途にはTypeScript SDKを直接使用してください：

シークレット作成 — Secret.create()（MCPサーバーは既存のシークレットをバインドするのみです）。
ストリーミングおよび対話型コマンド — ストリーミングのrun()コールバックとcommands.spawn（stdin、シグナル、長時間実行プロセス）。
大規模またはストリーミング転送 — ディレクトリのダウンロードはsandbox_files_download_dirを介して最大10 MiBまでサポートされています。それを超える場合（およびアーカイブ/ストリーミングアップロード、または1 MiBの読み取り/8 MiBのインライン書き込み上限を超える単一ファイルの場合）は、SDK/CLI（files.downloadDir、ストリーミングアップロード）を使用してください。
請求とプロバイダー検出 — 使用状況データと、シークレットプロバイダー設定用のProvider.list()。

これらはフォローアップとして追跡されています。

仕組み

サーバーはTypeScript SDKをラップし、コントロールプレーンのSUPERSERVE_API_KEYのみを保持します。各ツール呼び出しは、IDによってターゲットサンドボックスに接続します。SDKはサンドボックスごとのデータプレーンアクセストークンを内部的に管理し、再開時にローテーションするため、モデルに公開されたり、ツール出力に返されたりすることはありません。ツールはステートレスです — 隠れた「現在のサンドボックス」はありません — これにより、マルチターンおよび並列ツール呼び出し全体で動作が予測可能になります。

トラブルシューティング

ツールが表示されない、またはサーバーが起動しない。 原因はほとんどの場合APIキーです — MCPクライアントはシェルから環境変数を継承しません。ターミナルだけでなく、サーバーのenvブロックにSUPERSERVE_API_KEYを設定してください（インストールを参照）。
Authentication failed。 キーが欠落しているか無効です。本番キーはss_live_で始まります。APIキーページで作成してください。
最初の呼び出しが遅い。 npxは初回使用時にパッケージをダウンロードしてキャッシュします。以降の起動は高速です。
Node 18+が必要。 ローカルサーバーはnpxを介してNode上で実行されます。（ホステッドエンドポイントにはローカルランタイムの要件はありません。）
ホステッドエンドポイントからの401 Unauthorized。 ベアラートークンが欠落しているか、有効なss_live_キーではありません。Authorization: Bearer ss_live_…として送信してください（ホステッドを参照）。