Superserve Sandbox MCP

공식

Superserve가 호스팅하는 에이전트용 보안 가상 머신

superserve.ai에서 보기

Superserve Sandbox MCP(으)로 무엇을 할 수 있나요?

  • 샌드박스 생성 및 실행 — 어시스턴트에게 샌드박스를 실행하고 sandbox_create 및 sandbox_exec를 사용하여 python --version 같은 명령을 실행하도록 요청하세요.
  • 샌드박스에서 파일 관리 — sandbox_files_read, sandbox_files_write, sandbox_files_list를 사용하여 어시스턴트가 샌드박스 내부의 파일을 읽거나 쓰거나 나열하도록 하세요.
  • 네트워크 액세스 제어 — sandbox_create 또는 sandbox_update에서 이그레스 규칙을 구성하여 아웃바운드 대상을 허용하거나 차단한 다음, sandbox_network_log로 트래픽을 감사하세요.
  • 미리보기 URL 게시 — 어시스턴트에게 sandbox_preview_url을 호출하여 실행 중인 서비스를 공개하거나 만료되는 비공개 링크를 얻도록 요청하세요.
  • GUI 데스크톱 구동 — sandbox_computer를 사용하여 데스크톱 샌드박스에서 스크린샷, 클릭, 입력, 스크롤을 수행하여 브라우저 자동화 작업을 처리하세요.
  • 샌드박스 수명 주기 관리 — sandbox_pause, sandbox_resume, sandbox_kill로 샌드박스를 일시 중지, 재개 또는 영구 삭제하세요.

문서

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_computerGUI 데스크톱 샌드박스 제어: 스크린샷, 마우스, 키보드, 스크롤, 크기 조정, 뷰어 URL. 호출당 하나의 작업.
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(도메인 패턴, IP 또는 CIDR)은 허용 대상을 추가합니다. deny_out(IP 또는 CIDR, 도메인 없음)은 차단합니다. allow_out만으로는 샌드박스를 잠그지 않습니다 — 엄격한 허용 목록의 경우 deny_out: ["0.0.0.0/0"]와 결합하세요(모두 거부 후 나열된 대상 허용). 허용 목록에 도메인 규칙이 있거나 워크로드가 호스트 이름을 확인하는 경우 샌드박스의 DNS 확인자 1.1.1.1/32 및 8.8.8.8/32도 허용하세요. 모두 거부는 DNS도 차단하기 때문입니다. IP 전용 허용 목록에서는 이를 제외하세요. 허용된 확인자는 추가 아웃바운드 채널일 뿐입니다. 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 참조.

컴퓨터 사용

sandbox_computer는 superserve/desktop와 같은 데스크톱 템플릿에서 생성된 샌드박스의 GUI 데스크톱을 제어합니다. 호출당 하나의 action를 컴퓨터 사용 모델이 생성하는 어휘로 사용합니다: screenshot, left_click, right_click, middle_click, double_click, triple_click, left_click_drag, left_mouse_down, left_mouse_up, mouse_move, key, type, scroll, wait, resize, stream_url. 포인터 작업은 화면 픽셀(원점 왼쪽 위)의 coordinate: [x, y]를 사용합니다. key 및 type는 text를 사용합니다. scroll는 scroll_direction와 선택적 scroll_amount를 사용합니다.

sandbox_create    { name: "browser", from_template: "superserve/desktop" }
sandbox_computer  { sandbox_id: "a1b2c3…", action: "left_click", coordinate: [640, 32] }
                    → text "left_click done (1280x800)" + image/png
sandbox_computer  { sandbox_id: "a1b2c3…", action: "type", text: "https://example.com" }
sandbox_computer  { sandbox_id: "a1b2c3…", action: "key", text: "Return" }

입력 작업은 결과의 새 스크린샷을 반환하므로 모델의 행동-후-확인 턴은 하나의 도구 호출입니다. 연속으로 여러 작업을 보낼 때 screenshot_after: false를 전달하세요. wait는 샌드박스에 요청하지 않고 duration_ms 동안 일시 중지합니다(최대 10초). stream_url는 샌드박스의 미리보기 정책에 따라 데스크톱용 라이브 브라우저 뷰어를 반환합니다.

입력 작업이 실패하면 입력이 이미 전달되었을 수 있습니다. 도구는 이를 알리고 에이전트에게 반복하기 전에 스크린샷을 찍도록 요청합니다. 기본 SDK 표면은 데스크톱 가이드를 참조하세요.

아직 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 서버가 래핑하는 라이브러리.

이 문서는 개발자 문서 플랫폼인 Mintlify에서 구축 및 호스팅됩니다.