Superserve Sandbox MCP

chính thức

Máy ảo an toàn cho các tác nhân được lưu trữ bởi Superserve

Xem trên superserve.ai

Bạn có thể làm gì với Superserve Sandbox MCP?

  • Tạo và chạy sandbox — Yêu cầu trợ lý của bạn khởi tạo một sandbox và thực thi các lệnh như python --version bằng cách sử dụng sandbox_create và sandbox_exec.
  • Quản lý tệp trong sandbox — Yêu cầu trợ lý đọc, ghi hoặc liệt kê các tệp bên trong sandbox bằng sandbox_files_read, sandbox_files_write và sandbox_files_list.
  • Kiểm soát truy cập mạng — Cấu hình các quy tắc egress trên sandbox_create hoặc sandbox_update để cho phép hoặc chặn các đích đến gửi ra, sau đó kiểm tra lưu lượng bằng sandbox_network_log.
  • Xuất bản URL xem trước — Yêu cầu trợ lý của bạn hiển thị một dịch vụ đang chạy bằng cách gọi sandbox_preview_url để nhận liên kết công khai hoặc liên kết riêng tư có thời hạn.
  • Điều khiển màn hình nền GUI — Sử dụng sandbox_computer để chụp màn hình, nhấp chuột, gõ phím hoặc cuộn bên trong sandbox màn hình nền cho các tác vụ tự động hóa trình duyệt.
  • Quản lý vòng đời sandbox — Tạm dừng, tiếp tục hoặc xóa vĩnh viễn sandbox bằng sandbox_pause, sandbox_resume và sandbox_kill.

Tài liệu

Máy chủ MCP

Tạo, chạy và quản lý các sandbox Superserve từ bất kỳ máy khách MCP nào.

Muốn để một tác nhân tự tạo sandbox? Máy chủ MCP này làm được điều đó.

Máy chủ MCP Superserve (@superserve/mcp) hiển thị các nguyên hàm sandbox dưới dạng công cụ Giao thức Ngữ cảnh Mô hình, để bất kỳ máy khách hỗ trợ MCP nào — Claude, Cursor, VS Code, Windsurf, Codex — đều có thể tạo sandbox, chạy lệnh, đọc và ghi tệp, xây dựng mẫu, môi giới bí mật và kiểm soát truy cập mạng trong một microVM Firecracker biệt lập.

Chạy theo hai cách: cục bộ qua stdio bằng npx, hoặc qua điểm cuối được lưu trữ tại https://mcp.superserve.ai mà không cần cài đặt cục bộ. Cả hai đều xác thực bằng SUPERSERVE_API_KEY của bạn và nhắm mục tiêu một sandbox cho mỗi lần gọi theo ID. Đây là một lớp bọc mỏng quanh SDK TypeScript, nên mã thông báo mặt phẳng dữ liệu cho từng sandbox không bao giờ đến được mô hình.

Bắt đầu nhanh

Thêm máy chủ vào máy khách của bạn (xem Cài đặt), sau đó yêu cầu tác nhân "tạo một sandbox và chạy python --version trong đó." Tác nhân gọi sandbox_create, rồi sandbox_exec, và báo cáo kết quả — không cần mã từ bạn.

Bạn cần một khóa API Superserve — hãy tạo một khóa trên trang khóa API. Không có cài đặt toàn cục; npx tải máy chủ về lần sử dụng đầu tiên.

Cài đặt

Lưu ý

Đặt SUPERSERVE_API_KEY trong env của máy chủ — máy khách MCP không kế thừa nó từ shell của bạn. Ưu tiên lời nhắc nhập bí mật hơn là dán khóa thô ở nơi máy khách của bạn hỗ trợ (xem VS Code bên dưới).

```bash theme={"theme":{"light":"github-light","dark":"vitesse-dark"}} claude mcp add superserve \ --env SUPERSERVE_API_KEY=ss_live_xxxxxxxxxxxxxxxx \ -- npx -y @superserve/mcp ``` Thêm vào `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" }
    }
  }
}
```
Thêm vào `.cursor/mcp.json` (dự án) hoặc `~/.cursor/mcp.json` (toàn cục): 
```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "command": "npx",
      "args": ["-y", "@superserve/mcp"],
      "env": { "SUPERSERVE_API_KEY": "ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```
Thêm vào `.vscode/mcp.json`. Khối `inputs` nhắc nhập khóa thay vì lưu trữ dưới dạng văn bản thuần: 
```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}" }
    }
  }
}
```
Thêm vào `~/.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" }
    }
  }
}
```
Thêm vào `~/.codex/config.toml`. `env_vars` chuyển tiếp `SUPERSERVE_API_KEY` từ môi trường của bạn, nên khóa thô không được lưu trong tệp cấu hình (hãy xuất nó trong shell trước). Codex cũng đọc `instructions` của máy chủ để có hướng dẫn quy trình làm việc xuyên công cụ. 
```toml theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
[mcp_servers.superserve]
command = "npx"
args = ["-y", "@superserve/mcp"]
env_vars = ["SUPERSERVE_API_KEY"]
```

Đối với điểm cuối [được lưu trữ](#hosted-remote), hãy dùng `url = "https://mcp.superserve.ai"` với `bearer_token_env_var = "SUPERSERVE_API_KEY"`.

Được lưu trữ (từ xa)

Không muốn chạy bất cứ thứ gì cục bộ? Điểm cuối được lưu trữ tại https://mcp.superserve.ai nói chuyện qua Streamable HTTP — không cần npx, không cần Node. Gửi khóa API Superserve của bạn dưới dạng mã thông báo bearer. Điểm cuối không trạng thái và có phạm vi tài khoản (khóa của bạn đã ánh xạ tới nhóm của bạn), và mã thông báo mặt phẳng dữ liệu cho từng sandbox không bao giờ rời khỏi máy chủ.

Lưu ý

Xác thực Bearer hoạt động trong bất kỳ máy khách nào cho phép bạn đặt tiêu đề yêu cầu — Claude Code, Cursor, VS Code và bộ kết nối Anthropic Messages API. Claude.ai, Giao diện Kết nối Tùy chỉnh của Claude Desktop và chế độ nhà phát triển ChatGPT không cung cấp trường bearer tĩnh / tiêu đề tùy chỉnh (chúng mong đợi OAuth), mà điểm cuối được lưu trữ chưa hỗ trợ — hãy dùng bản cục bộ ở đó.

```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" ``` Thêm vào `.cursor/mcp.json` (dự án) hoặc `~/.cursor/mcp.json` (toàn cục): 
```json theme={"theme":{"light":"github-light","dark":"vitesse-dark"}}
{
  "mcpServers": {
    "superserve": {
      "url": "https://mcp.superserve.ai",
      "headers": { "Authorization": "Bearer ss_live_xxxxxxxxxxxxxxxx" }
    }
  }
}
```
Thêm vào `.vscode/mcp.json`. Khối `inputs` nhắc nhập khóa thay vì lưu trữ dưới dạng văn bản thuần: 
```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}" }
    }
  }
}
```
Truyền nó như một bộ kết nối trong yêu cầu [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"
    }
  ]
}
```

Các công cụ và hành vi giống hệt máy chủ cục bộ — điểm khác biệt duy nhất là phương thức truyền tải và khóa di chuyển dưới dạng tiêu đề bearer thay vì biến env.

Công cụ

Công cụChức năng
sandbox_createTạo một sandbox mới; trả về id của nó. Chấp nhận secrets, quy tắc egress và preview_access.
sandbox_updateThay đổi siêu dữ liệu, quy tắc egress, cửa sổ vòng đời hoặc preview_access.
sandbox_listLiệt kê các sandbox của bạn (đang hoạt động và đã tạm dừng), có thể lọc theo siêu dữ liệu.
sandbox_infoLấy trạng thái, tài nguyên, siêu dữ liệu, quy tắc mạng và ràng buộc bí mật của một sandbox. Chỉ đọc.
sandbox_execChạy một lệnh shell; trả về stdout, stderr, mã thoát. Tự động tiếp tục một sandbox đã tạm dừng.
sandbox_files_readĐọc một tệp (văn bản UTF-8 hoặc base64 cho tệp nhị phân).
sandbox_files_writeTạo hoặc ghi đè một tệp. Các thư mục cha được tạo tự động.
sandbox_files_listLiệt kê các mục của một thư mục (tên, loại, kích thước, thời gian sửa đổi).
sandbox_files_download_dirTải xuống một thư mục dưới dạng ZIP base64 (bỏ qua symlink). Giới hạn 10 MiB; lớn hơn → SDK/CLI.
sandbox_pauseTạm dừng một sandbox; trạng thái được bảo toàn.
sandbox_resumeTiếp tục một sandbox đã tạm dừng (thường không cần thiết — exec tự động tiếp tục).
sandbox_killXóa vĩnh viễn một sandbox.
sandbox_preview_urlXuất bản một cổng và trả về URL công khai sạch hoặc URL riêng tư có chữ ký hết hạn.
sandbox_network_logKiểm tra các kết nối đi của một sandbox (máy chủ, phán quyết, byte) mà không tiếp tục nó.
sandbox_computerĐiều khiển một sandbox desktop GUI: ảnh chụp màn hình, chuột, bàn phím, cuộn, thay đổi kích thước, URL xem. Một hành động mỗi lần gọi.
sandbox_template_listLiệt kê các mẫu (hình ảnh cơ sở) mà nhóm của bạn có thể khởi chạy.
sandbox_template_createXây dựng một mẫu tùy chỉnh với hình dạng vCPU/bộ nhớ/đĩa cụ thể hoặc phần mềm cài sẵn (không đồng bộ — thăm dò cho đến khi sẵn sàng).
secret_listLiệt kê các bí mật nhóm có thể ràng buộc (chỉ siêu dữ liệu — không bao giờ giá trị).
sandbox_attach_secretRàng buộc một bí mật đã lưu trữ vào một sandbox đang chạy dưới một biến môi trường.
sandbox_detach_secretGỡ bỏ ràng buộc bí mật khỏi một sandbox.

Hầu hết các công cụ nhận một sandbox_id; các ngoại lệ là sandbox_create, sandbox_list, sandbox_template_list, sandbox_template_create và secret_list. Bắt đầu với một trong những công cụ đó để lấy ID, rồi luồn nó vào các lần gọi sau. Các công cụ chỉ đọc (sandbox_list, sandbox_info, sandbox_files_read, sandbox_files_list, sandbox_files_download_dir, sandbox_network_log, sandbox_template_list, secret_list) được chú thích để máy khách có thể bỏ qua lời nhắc xác nhận; sandbox_preview_url là một ghi idempotent vì nó xuất bản cổng được yêu cầu, và sandbox_kill được chú thích là phá hủy.

Ví dụ

Một luồng tác nhân điển hình cho "khởi động một sandbox, viết một tập lệnh Python in các số nguyên tố đầu tiên và chạy nó":

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

Khi hoàn tất, tác nhân có thể sandbox_pause (trạng thái được bảo toàn, rẻ hơn để giữ) hoặc sandbox_kill (vĩnh viễn).

Cấu hình

BiếnBắt buộcMô tả
SUPERSERVE_API_KEYCóKhóa API Superserve của bạn (bắt đầu bằng ss_live_).
SUPERSERVE_BASE_URLKhôngGhi đè URL mặt phẳng điều khiển (mặc định là https://api.superserve.ai).

Hành vi và giới hạn

  • Tự động tiếp tục. sandbox_exec và các công cụ tệp tiếp tục một sandbox đã tạm dừng một cách minh bạch, nên tác nhân không bao giờ cần gọi sandbox_resume trước. sandbox_resume tồn tại chỉ để làm ấm một sandbox một cách tường minh.
  • Đầu ra bị giới hạn cho ngữ cảnh. sandbox_exec cắt stdout và stderr xuống 32 KiB mỗi cái — một kết quả bị cắt đặt truncated: true và báo cáo độ dài byte gốc. sandbox_files_read từ chối các tệp lớn hơn 1 MiB (nó không trả về nội dung một phần); lỗi cho bạn biết đọc một lát với sandbox_exec (ví dụ head -c) hoặc tải toàn bộ tệp bằng SDK/CLI. Nội dung nội tuyến sandbox_files_write bị giới hạn ở 8 MiB.
  • Thời gian chờ lệnh mặc định là 60 giây, giới hạn tối đa 10 phút. Ghi đè nó cho mỗi lần gọi bằng timeout_ms.
  • Egress có thể kiểm soát. allow_out (mẫu miền, IP hoặc CIDR) thêm đích được phép; deny_out (IP hoặc CIDR, không có miền) chặn chúng. Riêng allow_out không khóa chặt một sandbox — để có danh sách cho phép nghiêm ngặt, hãy kết hợp nó với deny_out: ["0.0.0.0/0"] (từ chối tất cả, rồi cho phép các đích được liệt kê). Nếu danh sách cho phép có quy tắc miền hoặc khối lượng công việc phân giải tên máy chủ, cũng cho phép các trình phân giải DNS của sandbox, 1.1.1.1/32 và 8.8.8.8/32, vì từ chối tất cả cũng chặn DNS; bỏ chúng khỏi danh sách cho phép chỉ IP, nơi một trình phân giải được phép chỉ là một kênh đi thêm. Đặt những thứ này trên sandbox_create hoặc sandbox_update, và kiểm tra những gì một sandbox thực sự đạt tới bằng sandbox_network_log.
  • Lỗi có thể hành động. Một lần gọi công cụ thất bại trả về một thông báo ngắn cho tác nhân biết phải làm gì tiếp theo — ví dụ "Đã đạt hạn mức sandbox. Tạm dừng hoặc giết một sandbox, hoặc thử lại sau." — thay vì một dấu vết ngăn xếp thô, để tác nhân có thể tự sửa.

Bí mật, mẫu và cổng

Bí mật. Đừng truyền thông tin xác thực dưới dạng env_vars văn bản thuần. Thay vào đó:

  1. Tạo bí mật một lần bằng SDK TypeScript (Secret.create()) hoặc bảng điều khiển — giá trị thô không bao giờ đi qua tác nhân hoặc máy chủ MCP, nên việc tạo bí mật cố ý không phải là một công cụ MCP.
  2. Khám phá các bí mật có thể ràng buộc bằng secret_list (chỉ siêu dữ liệu — giá trị không bao giờ rời khỏi nền tảng).
  3. Ràng buộc khi tạo — secrets: { ANTHROPIC_API_KEY: "anthropic-prod" } trên sandbox_create — hoặc sau đó bằng sandbox_attach_secret / sandbox_detach_secret.

Sandbox thấy một mã thông báo proxy; nền tảng hoán đổi thông tin xác thực thực chỉ cho các yêu cầu đi đến các máy chủ được phép của bí mật.

Mẫu. Một sandbox kế thừa vCPU/bộ nhớ/đĩa từ mẫu của nó và không thể ghi đè chúng tại thời điểm sandbox_create. Để có một hình dạng cụ thể (ví dụ, một sandbox 4 vCPU) hoặc phần mềm cài sẵn, hãy xây dựng một mẫu bằng sandbox_template_create, rồi thăm dò sandbox_template_list cho đến khi status của nó là ready trước khi truyền nó dưới dạng from_template.

Cổng. Các sandbox MCP mới dùng public làm truy cập mặc định cho các cổng mới được xuất bản; chỉ các cổng được xuất bản tường minh mới có thể truy cập. Truyền preview_access: "private" cho sandbox_create (hoặc sandbox_update) để thay đổi mặc định cho các cổng tương lai. Các cổng hiện có giữ chế độ riêng của chúng. Khởi động máy chủ với sandbox_exec, rồi gọi sandbox_preview_url; công cụ xuất bản idempotent cổng đó và dùng chế độ cổng được trả về để trả về một URL công khai sạch hoặc một URL riêng tư có chữ ký hết hạn. Các liên kết riêng tư mặc định một giờ; đặt expires_in_seconds thành một giá trị từ 1 đến 604800 giây. Xem URL xem trước.

Sử dụng máy tính

sandbox_computer điều khiển một desktop GUI trong một sandbox được tạo từ một mẫu desktop như superserve/desktop. Nó nhận một action mỗi lần gọi trong từ vựng mà các mô hình sử dụng máy tính phát ra: 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 và stream_url. Các hành động con trỏ nhận coordinate: [x, y] tính bằng pixel màn hình (gốc trên trái); key và type nhận text; scroll nhận scroll_direction và một scroll_amount tùy chọn.

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

Các hành động đầu vào trả về một ảnh chụp màn hình mới của kết quả, nên lượt hành-động-rồi-nhìn của mô hình là một lần gọi công cụ; truyền screenshot_after: false khi gửi nhiều hành động liên tiếp. wait tạm dừng trong duration_ms (giới hạn ở 10 giây) mà không có yêu cầu đến sandbox. stream_url trả về một trình xem trình duyệt trực tiếp cho desktop theo chính sách xem trước của sandbox.

Nếu một hành động đầu vào thất bại, đầu vào có thể đã được gửi. Công cụ nói điều đó và yêu cầu tác nhân chụp ảnh màn hình trước khi lặp lại. Xem Hướng dẫn Desktop cho bề mặt SDK bên dưới.

Chưa có trong bề mặt MCP

Máy chủ MCP bao phủ vòng lặp tác nhân thông thường; bảng trên là bộ công cụ v1 đầy đủ. Một vài khả năng của SDK chưa được hiển thị — hãy sử dụng trực tiếp TypeScript SDK cho:

  • Tạo bí mật — Secret.create() (máy chủ MCP chỉ liên kết các bí mật hiện có).
  • Lệnh phát trực tuyến và tương tác — phát trực tuyến run() callbacks và commands.spawn (stdin, tín hiệu, các tiến trình chạy lâu).
  • Truyền tải lớn hoặc phát trực tuyến — tải xuống thư mục được hỗ trợ tối đa 10 MiB qua sandbox_files_download_dir; vượt quá giới hạn đó (và đối với tải lên lưu trữ/phát trực tuyến hoặc tệp đơn lẻ vượt quá giới hạn đọc 1 MiB / ghi nội tuyến 8 MiB), hãy sử dụng SDK/CLI (files.downloadDir, tải lên phát trực tuyến).
  • Thanh toán và khám phá nhà cung cấp — dữ liệu sử dụng và Provider.list() để thiết lập nhà cung cấp bí mật.

Những điều này được theo dõi như các mục tiếp theo.

Cách hoạt động

Máy chủ bao bọc TypeScript SDK và chỉ giữ SUPERSERVE_API_KEY mặt phẳng điều khiển của bạn. Mỗi lệnh gọi công cụ kết nối đến sandbox mục tiêu theo ID; SDK quản lý mã thông báo truy cập mặt phẳng dữ liệu riêng cho từng sandbox nội bộ và xoay vòng mã này khi tiếp tục, vì vậy mã không bao giờ bị lộ cho mô hình hoặc trả về trong đầu ra công cụ. Các công cụ không trạng thái — không có "sandbox hiện tại" ẩn — giúp hành vi dự đoán được qua các lệnh gọi công cụ đa lượt và song song.

Khắc phục sự cố

  • Công cụ không xuất hiện hoặc máy chủ không khởi động được. Khóa API gần như luôn là nguyên nhân — máy khách MCP không kế thừa biến môi trường từ shell của bạn. Đặt SUPERSERVE_API_KEY trong khối env của máy chủ (xem Cài đặt), không chỉ trong terminal của bạn.
  • Authentication failed. Khóa bị thiếu hoặc không hợp lệ. Khóa sản xuất bắt đầu bằng ss_live_; tạo một khóa trên trang khóa API.
  • Lần gọi đầu tiên chậm. npx tải xuống gói khi sử dụng lần đầu và lưu vào bộ nhớ đệm; các lần khởi động sau nhanh hơn.
  • Yêu cầu Node 18+. Máy chủ cục bộ chạy trên Node qua npx. (Điểm cuối được lưu trữ không có yêu cầu thời gian chạy cục bộ.)
  • 401 Unauthorized từ điểm cuối được lưu trữ. Mã thông báo bearer bị thiếu hoặc không phải là khóa ss_live_ hợp lệ. Gửi mã dưới dạng Authorization: Bearer ss_live_… (xem Được lưu trữ).

Liên quan

Tạm dừng, tiếp tục và xóa sandbox. Thực thi, phát trực tuyến, cwd, env và thời gian chờ. Môi giới khóa nhà cung cấp mà không để lộ chúng cho sandbox. Thư viện mà máy chủ MCP bao bọc.

Tài liệu này được xây dựng và lưu trữ trên Mintlify, một nền tảng tài liệu dành cho nhà phát triển.