Superserve Sandbox MCP

公式

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

superserve.ai で表示このMCPを試すスポンサー

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

サンドボックスの作成と実行 — アシスタントにsandbox_createでサンドボックスを起動させ、sandbox_execでpython --versionなどのコマンドを実行させます。
サンドボックス内のファイル管理 — sandbox_files_write、sandbox_files_read、sandbox_files_listを使用して、サンドボックス内のファイルを作成、表示、整理します。
サンドボックスのライフサイクル制御 — sandbox_pause、sandbox_resume、sandbox_killでサンドボックスを一時停止、再開、完全削除してリソースを管理します。
プレビューURLの公開 — sandbox_preview_urlを呼び出して実行中のサービスを公開し、公開リンクまたは期限付きのプライベートリンクを取得します。
シークレットの安全なバインド — sandbox_attach_secretとsandbox_detach_secretを使用して、保存済みのチームシークレットをサンドボックスにアタッチまたはデタッチし、生の値を公開しません。
カスタムテンプレートの構築 — sandbox_template_createで特定のCPU/メモリ/ディスク構成を持つ再利用可能なサンドボックステンプレートを作成し、sandbox_template_listで一覧表示します。

ドキュメント

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`、エグレスルール、`preview_access`を受け付けます。
`sandbox_update`	メタデータ、エグレスルール、ライフサイクルウィンドウ、または`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_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で上書きできます。
エグレスは制御可能です。 allow_out（ドメインパターンまたはCIDR）は許可先を追加し、deny_out（CIDRのみ）はブロックします。allow_outだけではサンドボックスをロックダウンしません。厳格な許可リストの場合は、deny_out: ["0.0.0.0/0"]（すべて拒否してからリストされた宛先を許可）と組み合わせてください。これらは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でテンプレートを構築し、statusがreadyになるまでsandbox_template_listをポーリングしてから、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を参照してください。

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

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

シークレットの作成 — Secret.create()（MCPサーバーは既存のシークレットをバインドするのみです）。
ストリーミングおよび対話型コマンド — ストリーミング run() コールバックと commands.spawn（標準入力、シグナル、長時間実行プロセス）。
大容量またはストリーミング転送 — ディレクトリのダウンロードは 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_… として送信してください（ホスト型を参照）。