Superserve Sandbox MCP

公式

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

superserve.ai で表示

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

隔離されたサンドボックスを作成 — アシスタントに sandbox_create でFirecrackerマイクロVMを起動させ、必要に応じてシークレットや出力ルールを付与します。
サンドボックス内でシェルコマンドを実行 — sandbox_exec でコマンドを実行し、stdout、stderr、終了コードを取得します（一時停止中のサンドボックスは自動再開）。
サンドボックス内のファイルを読み書き — sandbox_files_read と sandbox_files_write でファイルを確認・配置し、親ディレクトリは自動生成されます。
サンドボックスから公開エンドポイントを公開 — サーバープロセスを起動し、sandbox_preview_url を呼び出すと、待受ポートに公開アクセス可能なURLが取得できます。
送信ネットワークトラフィックを監査 — sandbox_network_log で、サンドボックスが接続したホストと、許可・拒否の結果を確認できます。
カスタムテンプレートを構築・管理 — sandbox_template_create でvCPU/メモリ/ディスクやプリインストールソフトウェアを指定したテンプレートを作成し、そこからサンドボックスを起動します。

ドキュメント

MCP サーバー

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

Superserve MCP サーバー (@superserve/mcp) は、サンドボックスプリミティブを Model Context Protocol ツールとして公開するため、Claude、Cursor、VS Code、Windsurf、Codex など、MCP 対応のクライアントであれば、隔離された 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 を期待）、ホスト型エンドポイントはまだこれをサポートしていません。その場合は [ローカル](#install) インストールを使用してください。 ```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 ルールを受け入れます。
`sandbox_update`	作成後にサンドボックスのメタデータまたは Egress（`allow_out`/`deny_out`）ルールを変更します。
`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 を構築します（認証なし。そのポート上のものはすべてインターネットに公開されます）。
`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_preview_url、sandbox_template_list、secret_list）は、クライアントが確認プロンプトをスキップできるように注釈が付けられています。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（ドメインパターンまたは 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 として渡します。

ポート。 サンドボックスでサーバーを起動し（sandbox_exec、例: python3 -m http.server 8000）、sandbox_preview_url を呼び出してそのパブリック URL を取得します。ポートにバインドされたプロセスは、認証なしで https://{port}-{id}.sandbox.superserve.ai で到達可能です。公開する予定のポートのみを公開してください。

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_… として送信してください（ホステッドを参照）。