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에서 샌드박스를 생성하고, 명령을 실행하고, 파일을 읽고 쓰고, 템플릿을 빌드하고, 비밀번호를 중개하고, 네트워크 액세스를 제어할 수 있습니다.

두 가지 방법으로 실행할 수 있습니다: 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의 Custom Connector UI, ChatGPT 개발자 모드는 정적 베어러 / 사용자 정의 헤더 필드를 제공하지 않습니다(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하나의 샌드박스 상태, 리소스, 메타데이터, 네트워크 규칙, 비밀 바인딩을 가져옵니다. 읽기 전용.
sandbox_exec셸 명령 실행; stdout, stderr, 종료 코드를 반환합니다. 일시 중지된 샌드박스를 자동 재개합니다.
sandbox_files_read파일 읽기(UTF-8 텍스트 또는 바이너리의 base64).
sandbox_files_write파일 생성 또는 덮어쓰기. 상위 디렉터리는 자동으로 생성됩니다.
sandbox_files_list디렉터리 항목 목록(이름, 유형, 크기, 수정 시간).
sandbox_files_download_dir디렉터리를 base64 ZIP으로 다운로드(심볼릭 링크 건너뜀). 10MiB로 제한; 더 큰 경우 → 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를 각각 32KiB로 자릅니다 — 잘린 결과는 truncated: true을 설정하고 원래 바이트 길이를 보고합니다. sandbox_files_read은 1MiB보다 큰 파일을 거부합니다(부분 콘텐츠를 반환하지 않음); 오류는 sandbox_exec으로 슬라이스를 읽거나(예: head -c) SDK/CLI로 전체 파일을 다운로드하라고 알려줍니다. sandbox_files_write 인라인 콘텐츠는 8MiB로 제한됩니다.
  • 기본 명령 시간 제한은 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으로 전달하세요.

포트. 새 MCP 샌드박스는 새로 게시된 포트의 기본 액세스로 public을 사용합니다; 명시적으로 게시된 포트만 연결 가능합니다. sandbox_create(또는 sandbox_update)에 preview_access: "private"을 전달하여 향후 포트의 기본값을 변경하세요. 기존 포트는 자체 모드를 유지합니다. sandbox_exec으로 서버를 시작한 다음 sandbox_preview_url을 호출하세요; 도구는 해당 포트 하나를 멱등적으로 게시하고 반환된 포트 모드를 사용하여 깨끗한 공개 URL 또는 만료되는 비공개 서명 URL을 반환합니다. 비공개 링크는 기본적으로 1시간; expires_in_seconds을 1~604800초 값으로 설정하세요. 미리보기 URL 참조.

아직 MCP 표면에 없는 기능

MCP 서버는 일반적인 에이전트 루프를 다룹니다; 위 표는 완전한 v1 도구 세트입니다. 몇 가지 SDK 기능은 아직 노출되지 않았습니다 — TypeScript SDK를 직접 사용하세요:

  • 비밀 생성 — Secret.create() (MCP 서버는 기존 비밀만 바인딩합니다).
  • 스트리밍 및 대화형 명령 — run() 콜백 및 commands.spawn 스트리밍 (stdin, 신호, 장기 실행 프로세스).
  • 대용량 또는 스트리밍 전송 — 디렉터리 다운로드는 sandbox_files_download_dir을 통해 최대 10MiB까지 지원됩니다. 그 이상(및 아카이브/스트리밍 업로드 또는 1MiB 읽기 / 8MiB 인라인 쓰기 한도를 초과하는 단일 파일)의 경우 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 서버가 래핑하는 라이브러리.