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)는 샌드박스 기본 요소를 모델 컨텍스트 프로토콜 도구로 노출하므로, Claude, Cursor, VS Code, Windsurf, Codex 등 MCP 지원 클라이언트라면 무엇이든 격리된 Firecracker 마이크로VM에서 샌드박스를 생성하고, 명령을 실행하고, 파일을 읽고 쓰고, 템플릿을 빌드하고, 비밀을 중개하고, 네트워크 접근을 제어할 수 있습니다.

두 가지 방식으로 실행하세요: 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의 호스팅 엔드포인트는 스트리밍 가능 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 및 송신 규칙을 허용합니다.
sandbox_update생성 후 샌드박스의 메타데이터 또는 송신(allow_out/deny_out) 규칙을 변경합니다.
sandbox_list샌드박스(활성 및 일시 중지)를 메타데이터로 필터링하여 나열합니다.
sandbox_info하나의 샌드박스 상태, 리소스, 메타데이터, 네트워크 규칙 및 비밀 바인딩을 가져옵니다. 읽기 전용입니다.
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로 재정의하세요.
  • 송신 제어 가능. allow_out (도메인 패턴 또는 CIDR)은 허용된 대상을 추가하고, deny_out (CIDR만 해당)은 차단합니다. allow_out만으로는 샌드박스를 잠그지 않습니다. 엄격한 허용 목록을 위해서는 deny_out: ["0.0.0.0/0"]와 결합하세요(모두 거부 후 나열된 대상 허용). sandbox_create 또는 sandbox_update에서 설정하고, sandbox_network_log로 샌드박스가 실제로 도달한 대상을 감사하세요.
  • 오류는 실행 가능합니다. 실패한 도구 호출은 에이전트가 자체 수정할 수 있도록 원시 스택 추적 대신 다음에 수행할 작업을 알려주는 짧은 메시지를 반환합니다(예: "샌드박스 할당량에 도달했습니다. 샌드박스를 일시 중지하거나 종료하거나 나중에 다시 시도하세요.").

비밀, 템플릿 및 포트

비밀. 자격 증명을 일반 텍스트 env_vars로 전달하지 마세요. 대신:

  1. TypeScript SDK (Secret.create()) 또는 콘솔을 사용하여 비밀을 한 번 생성하세요. 원시 값은 에이전트나 MCP 서버를 통해 전달되지 않으므로 비밀 생성은 의도적으로 MCP 도구가 아닙니다.
  2. secret_list로 바인딩 가능한 비밀을 검색하세요(메타데이터만 — 값은 플랫폼을 떠나지 않음).
  3. 생성 시(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_…로 전송하세요(호스팅 참조).

관련 항목

샌드박스를 일시 중지, 재개 및 삭제합니다. Exec, 스트리밍, cwd, env 및 시간 초과. 샌드박스에 노출하지 않고 브로커 제공자 키를 사용합니다. MCP 서버가 래핑하는 라이브러리입니다.