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 một sandbox cách ly — yêu cầu trợ lý khởi chạy một microVM Firecracker với sandbox_create, tùy chọn đính kèm bí mật và quy tắc truy cập ra ngoài.
  • Chạy lệnh shell bên trong sandbox — thực thi lệnh qua sandbox_exec và nhận lại stdout, stderr cùng mã thoát (tự động tiếp tục các sandbox đã tạm dừng).
  • Đọc và ghi tệp trong sandbox — sử dụng sandbox_files_read và sandbox_files_write để kiểm tra hoặc đặt tệp, với tính năng tự động tạo thư mục cha.
  • Công khai một điểm cuối từ sandbox — khởi động một tiến trình máy chủ và gọi sandbox_preview_url để lấy một URL có thể truy cập công khai cho một cổng đang lắng nghe.
  • Kiểm tra lưu lượng mạng đi ra — kiểm tra các máy chủ mà sandbox đã liên hệ và xem chúng được phép hay bị từ chối bằng sandbox_network_log.
  • Xây dựng và quản lý các mẫu tùy chỉnh — tạo một mẫu với vCPU/bộ nhớ/đĩa cụ thể hoặc phần mềm đã cài đặt sẵn bằng sandbox_template_create, sau đó khởi chạy các sandbox từ mẫu đó.

Tài liệu

MCP Server

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

MCP server Superserve (@superserve/mcp) hiển thị các nguyên hàm sandbox dưới dạng công cụ Model Context Protocol, vì vậy bất kỳ client nào hỗ trợ MCP — 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 cô lập.

Chạy theo hai cách: cục bộ qua stdio bằng npx, hoặc dùng hosted endpoint 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 trên TypeScript SDK, vì vậy token mặt phẳng dữ liệu cho mỗi sandbox không bao giờ đến được mô hình.

Bắt đầu nhanh

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

Bạn cần một khóa API Superserve — tạo một khóa trên trang API key. Không có cài đặt toàn cục; npx tải server khi sử dụng lần đầu.

Cài đặt

Đặt `SUPERSERVE_API_KEY` trong `env` của server — các client 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 thay vì dán khóa thô vào nơi client 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 túy: 
```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, vì vậy khóa thô không được lưu trữ trong tệp cấu hình (xuất nó trong shell của bạn trước). Codex cũng đọc `instructions` của server để hướng dẫn quy trình làm việc đa 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 endpoint [hosted](#hosted-remote), sử dụng `url = "https://mcp.superserve.ai"` với `bearer_token_env_var = "SUPERSERVE_API_KEY"`.

Hosted (từ xa)

Không muốn chạy bất cứ thứ gì cục bộ? Hosted endpoint tại https://mcp.superserve.ai sử dụng 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 bearer token. Endpoint này không trạng thái và được giới hạn theo tài khoản (khóa của bạn đã ánh xạ tới nhóm của bạn), và token mặt phẳng dữ liệu cho mỗi sandbox không bao giờ rời khỏi server.

Xác thực Bearer hoạt động trong bất kỳ client nào cho phép bạn đặt tiêu đề yêu cầu — Claude Code, Cursor, VS Code và trình kết nối Anthropic Messages API. Claude.ai, Giao diện Custom Connector của Claude Desktop và chế độ nhà phát triển ChatGPT không cung cấp trường static-bearer / custom-header (chúng mong đợi OAuth), mà hosted endpoint chưa hỗ trợ — hãy sử dụng cài đặt [cục bộ](#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" ``` 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 túy: 
```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 trình 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ùng các công cụ và hành vi như server cục bộ — điểm khác biệt duy nhất là phương thức truyền tải và khóa được truyề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ó. Hoạt động và sẵn sàng ngay lập tức. Chấp nhận secrets và các quy tắc đi ra.
sandbox_updateThay đổi siêu dữ liệu hoặc quy tắc đi ra (allow_out/deny_out) của sandbox sau khi tạo.
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à liên kết 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 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_urlXây dựng URL công khai cho một cổng đang lắng nghe (không xác thực — bất cứ thứ gì trên cổng đó đều được hiển thị ra internet).
sandbox_network_logKiểm tra các kết nối ra bên ngoài của sandbox (máy chủ, phán quyết, byte). Tự động tiếp tục một sandbox đã tạm dừng.
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 cài đặt sẵn (bất đồ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ể liên kết (chỉ siêu dữ liệu — không bao giờ là giá trị).
sandbox_attach_secretLiên kết một bí mật đã lưu trữ với một sandbox đang chạy dưới một biến môi trường.
sandbox_detach_secretXóa liên kết bí mật khỏi 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 số đó để lấy ID, sau đó luồn nó vào các lệnh 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_preview_url, sandbox_template_list, secret_list) được chú thích để client có thể bỏ qua lời nhắc xác nhận; sandbox_kill được chú thích là có tính hủy hoại.

Ví dụ

Một luồng agent điển hình cho "khởi động một sandbox, viết một script Python in ra 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, agent có thể sandbox_pause (trạng thái được bảo toàn, rẻ hơn để giữ lại) 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 trong suốt tiếp tục một sandbox đã tạm dừng, vì vậy agent không bao giờ cần gọi sandbox_resume trước. sandbox_resume chỉ tồn tại để làm nóng sandbox một cách rõ ràng.
  • Đầu ra bị giới hạn cho ngữ cảnh. sandbox_exec cắt ngắn stdout và stderr xuống còn 32 KiB mỗi luồng — một kết quả bị cắt ngắn đặ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 hãy đọc một lát cắt bằng sandbox_exec (ví dụ: head -c) hoặc tải xuống 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.
  • Đi ra có thể kiểm soát. allow_out (mẫu tên miền hoặc CIDR) thêm các đích được phép; deny_out (chỉ CIDR) chặn chúng. Chỉ allow_out không khóa chặ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ả, sau đó cho phép các đích được liệt kê). Đặt những thứ này trên sandbox_create hoặc sandbox_update, và kiểm tra những gì sandbox thực sự đã truy cập bằng sandbox_network_log.
  • Lỗi có thể hành động. Một lệnh gọi công cụ thất bại trả về một thông báo ngắn cho agent biết phải làm gì tiếp theo — ví dụ: "Đã đạt đến hạn ngạch sandbox. Tạm dừng hoặc hủy một sandbox, hoặc thử lại sau." — thay vì một dấu vết ngăn xếp thô, để agent có thể tự sửa lỗi.

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 túy. Thay vào đó:

  1. Tạo bí mật một lần bằng TypeScript SDK (Secret.create()) hoặc bảng điều khiển — giá trị thô không bao giờ đi qua agent hoặc MCP server, vì vậy việc tạo bí mật có chủ ý không phải là một công cụ MCP.
  2. Khám phá các bí mật có thể liên kết 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. Liên kết 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 token 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 ra bên ngoà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ó được một hình dạng cụ thể (ví dụ: sandbox 4 vCPU) hoặc phần mềm được cài đặt sẵn, hãy xây dựng một mẫu bằng sandbox_template_create, sau đó thăm dò sandbox_template_list cho đến khi status của nó là ready trước khi truyền nó làm from_template.

Cổng. Khởi động một server trong sandbox (sandbox_exec, ví dụ: python3 -m http.server 8000), sau đó gọi sandbox_preview_url để lấy URL công khai của nó. Bất kỳ tiến trình nào liên kết với một cổng đều có thể truy cập được tại https://{port}-{id}.sandbox.superserve.ai với không xác thực — chỉ hiển thị các cổng bạn dự định công khai.

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

MCP server bao gồm vòng lặp agent phổ biến; bảng trên là bộ công cụ v1 hoàn chỉnh. Một số khả năng 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() (MCP server 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 các callback run() và commands.spawn (stdin, tín hiệu, tiến trình chạy dài).
  • Truyền tải lớn hoặc phát trực tuyến — tải xuống thư mục được hỗ trợ lên đến 10 MiB qua sandbox_files_download_dir; vượt quá mức đó (và đối với tải lên lưu trữ/phát trực tuyến hoặc cá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 thức 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ần gọi công cụ kết nối đến sandbox đích bằng ID; SDK quản lý mã thông báo truy cập mặt phẳng dữ liệu cho từng sandbox một cách nội bộ và xoay vòng nó khi tiếp tục, vì vậy nó không bao giờ bị lộ cho mô hình hoặc được trả về trong đầu ra của công cụ. Các công cụ là phi trạng thái — không có "sandbox hiện tại" ẩn nào — điều này giữ cho hành vi có thể dự đoán được qua các lần 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 hầu như luôn là nguyên nhân — các 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 production 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 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 sẽ nhanh.
  • 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 runtime 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 nó 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, truyền phát, 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.