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.aiDùng thử MCP nàyĐược tài trợ

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 bằng sandbox_create và thực thi các lệnh như python --version qua sandbox_exec.
  • Quản lý tệp trong sandbox — Sử dụng sandbox_files_write, sandbox_files_read và sandbox_files_list để tạo, xem hoặc sắp xếp các tệp bên trong sandbox.
  • Kiểm soát 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 để quản lý tài nguyên.
  • Xuất bản URL xem trước — 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.
  • Liên kết bí mật một cách an toàn — Đính kèm hoặc gỡ bỏ các bí mật của nhóm đã lưu vào sandbox qua sandbox_attach_secret và sandbox_detach_secret mà không tiết lộ giá trị thô.
  • Xây dựng mẫu tùy chỉnh — Tạo các mẫu sandbox có thể tái sử dụng với cấu hình CPU/bộ nhớ/ổ đĩa cụ thể bằng sandbox_template_create và liệt kê chúng bằng sandbox_template_list.

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.

Bạn 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ụ Model Context Protocol, để 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 TypeScript SDK, 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 việc 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 đ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 đ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 Custom Connector 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ài đặt 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ó dưới dạng 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_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_secretXóa một ràng buộc bí mật khỏi một sandbox.

Hầu hết các công cụ nhận 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_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 thao tác 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 chỉ tồn tại để 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 bớ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 bảo bạn đọc một lá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 được 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 tên miền hoặc CIDR) thêm các đích được phép; deny_out (chỉ CIDR) chặn chúng. allow_out một mình không khóa 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ả, sau đó cho phép các đích được liệt kê). Đặt các điều này trên sandbox_create hoặc sandbox_update, và kiểm tra những gì một 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 bảo tác nhân phải làm gì tiếp theo — ví dụ: "Đã đạt hạn mức sandbox. Hãy tạm dừng hoặc xóa 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 TypeScript SDK (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 chỉ hoán đổi thông tin xác thực thực 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, sau đó 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ủ bằng sandbox_exec, sau đó 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ả 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.

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

Máy chủ MCP bao phủ vòng lặp tác nhân phổ biến; bảng trên là bộ công cụ v1 hoàn chỉnh. Một vài khả năng SDK chưa được hiển thị — hãy 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 tương tác và phát trực tuyến — 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 thư mục được hỗ trợ lên đến 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 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 mục này được theo dõi như các công việc tiếp theo.

Cách hoạt động

Server bao bọc TypeScript SDK và chỉ giữ SUPERSERVE_API_KEY control-plane 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 data-plane 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 server không khởi động được. Nguyên nhân gần như luôn là khóa API — MCP clients 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 server (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 gói trong lần sử dụng đầu tiên và lưu vào bộ nhớ đệm; các lần khởi động sau nhanh.
  • Yêu cầu Node 18+. Server 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, 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à MCP server bao bọc.