Superserve Sandbox

@superserve/mcp

Superserve サンドボックス用の Model Context Protocol サーバーです。Claude、Cursor、VS Code、Windsurf、Codex など、あらゆる MCP クライアントから、分離された Firecracker マイクロ VM を作成し、コマンドを実行し、管理できます。

npx 経由で stdio を使用してローカルで動作します。Superserve API キーで認証し、呼び出しごとに ID で対象のサンドボックスを指定します。

インストール

MCP クライアントに追加し、env に SUPERSERVE_API_KEY を設定してください（クライアントはシェルからこの環境変数を引き継ぎません）。キーは console.superserve.ai で作成できます。

Claude Code:

claude mcp add superserve \
  --env SUPERSERVE_API_KEY=ss_live_xxxxxxxxxxxxxxxx \
  -- npx -y @superserve/mcp

Claude Desktop / Cursor / Windsurf（claude_desktop_config.json、.cursor/mcp.json、mcp_config.json）：

{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}

VS Code（.vscode/mcp.json。キーの入力を求められます）：

{
  "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}" }
    }
  }
}

Codex（~/.codex/config.toml）— env_vars を使うと、キーをファイルに保存せず、環境変数から渡せます：

[mcp_servers.superserve]
command = "npx"
args = ["-y", "@superserve/mcp"]
env_vars = ["SUPERSERVE_API_KEY"]

ホステッド（リモート）

https://mcp.superserve.ai でホステッドインスタンスが稼働しています（Streamable HTTP）。ローカルへのインストールは不要です。Superserve API キーをベアラートークンとして送信してください。サーバーはステートレスで、アカウント単位で動作します（キーによってチームがすでに特定されます）。

ベアラー認証は Claude Code、Cursor、VS Code、Anthropic Messages API コネクターで使用できます。Claude.ai、Claude Desktop のカスタムコネクター UI、ChatGPT の開発者モードでは OAuth が必要です（固定ベアラーを指定するフィールドがありません）。ホステッドエンドポイントは現時点で OAuth に対応していません。

Claude Code:

claude mcp add --transport http superserve https://mcp.superserve.ai \
  --header "Authorization: Bearer ss_live_xxxxxxxxxxxxxxxx"

Cursor / VS Code（.cursor/mcp.json、.vscode/mcp.json）：

{
  "servers": {
    "superserve": {
      "type": "http",
      "url": "https://mcp.superserve.ai",
      "headers": { "Authorization": "Bearer ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}

ホステッドサーバーの実行

同じパッケージにホステッドサーバーも含まれています。単体で実行できます（セルフホスト／ステージング）：

PORT=8080 SUPERSERVE_BASE_URL=https://api.superserve.ai \
  npx -y -p @superserve/mcp superserve-mcp-http

または、Web 標準のハンドラーを任意の fetch ランタイム（例：Next.js のルートハンドラー）にマウントできます：

import { handleMcpRequest } from "@superserve/mcp/http"

export const POST = (req: Request) => handleMcpRequest(req)

MCP エンドポイントとして /（POST）を提供し、稼働確認用の GET /health を用意しています。設定項目は PORT（デフォルトは 8080）と SUPERSERVE_BASE_URL（任意）です。API キーは各リクエストのベアラーヘッダーから読み取られ、ログには記録されません。

ツール

ツール	説明
sandbox_create	サンドボックスを作成し、その id を返します。secrets のバインドと送信ルールを指定できます。
sandbox_update	作成後に、サンドボックスのメタデータまたは送信（allow_out／deny_out）ルールを変更します。
sandbox_list	サンドボックス（アクティブおよび一時停止中）の一覧を表示します。メタデータで絞り込めます。
sandbox_info	サンドボックスのステータス、リソース、メタデータ、ネットワークルール、シークレットのバインドを取得します。
sandbox_exec	シェルコマンドを実行し、stdout、stderr、終了コードを返します。一時停止中のサンドボックスは自動的に再開します。
sandbox_computer	GUI デスクトップサンドボックスを操作します。スクリーンショット、マウス、キーボード、スクロール、サイズ変更、ライブビューアー URL に対応します。入力操作の結果として新しいスクリーンショット（JPEG）を返します。
sandbox_files_read	ファイルを読み込みます（UTF-8 テキストまたは base64）。1 MiB を超えるファイルは拒否されます。
sandbox_files_write	ファイルを作成または上書きします（インラインコンテンツの上限は 8 MiB）。
sandbox_files_list	ディレクトリの一覧を表示します。
sandbox_files_download_dir	ディレクトリを base64 の ZIP としてダウンロードします（シンボリックリンクはスキップ）。上限は 10 MiB です。
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 は除きます。シークレットの_作成_は意図的に公開されていません（生の値はエージェントの会話履歴ではなく、SDK／コンソールで扱うものです）。サーバーは既存のシークレットのみをバインドします。

設定

変数	必須	デフォルト
SUPERSERVE_API_KEY	はい	—
SUPERSERVE_BASE_URL	いいえ	https://api.superserve.ai

開発

bun install
bunx turbo run build     --filter=@superserve/mcp
bunx turbo run typecheck --filter=@superserve/mcp
bunx turbo run test      --filter=@superserve/mcp        # unit + in-memory integration (no credentials)
SUPERSERVE_API_KEY=ss_live_... bunx turbo run e2e --filter=@superserve/mcp   # live round-trip

このサーバーは @superserve/sdk を介した薄いアダプターです。サンドボックスごとのデータプレーンアクセストークンは SDK が管理し、モデルに公開されることはありません。

ライセンス

Apache-2.0