MCP server and tools
MCP (Model Context Protocol) lets an AI assistant use external tools. Connect WBX Sandbox and the assistant gets tools to create sandboxes, run commands and code, read and write files and run background jobs – everything runs on our servers, not on your computer.
Server address and sign-in
- The server address is always
https://sandbox.wbx.cz/mcp(Streamable HTTP). - Assistants that can't send an API key ask you to sign in to WBX Sandbox and approve access (OAuth); this creates an API key named “… (connected app)” in your team. To disconnect, delete that key in API keys. Only team owners and admins can approve.
- Clients that can send headers can use an API key directly:
Authorization: Bearer YOUR_API_KEY.
claude mcp add --transport http wbxsandbox https://sandbox.wbx.cz/mcp --header "Authorization: Bearer YOUR_API_KEY"
Local helper for stdio clients
For clients that can only start a local program. Download the small helper program and add it to your client's configuration, for example claude_desktop_config.json:
{
"mcpServers": {
"wbxsandbox": {
"command": "/path/to/wbxsandbox-mcp",
"args": ["-url", "https://sandbox.wbx.cz"],
"env": { "WBXSANDBOX_API_KEY": "YOUR_API_KEY" }
}
}
}
Helper downloads: macOS (Apple Silicon) · macOS (Intel) · Windows · Linux (x86-64) · Linux (ARM64) · SHA-256 checksums
Keep the API key in env, not in args – arguments are visible to other programs on the computer. On macOS and Linux make the file executable with chmod +x; on macOS also allow it with xattr -d com.apple.quarantine wbxsandbox-mcp-darwin-arm64. Windows may show a SmartScreen warning for the downloaded program. wbxsandbox-mcp -version prints the version; download it again after an update to get new tools.
Tools
| Tool | What it does |
|---|---|
create_sandbox | Start a sandbox from a template – optionally without internet, with allowed destinations only, or with IPv6 (ip: dual or ipv6). With a name, an existing sandbox of that name is reused (woken up if asleep), so files survive between chats |
run_command | Run a shell command |
run_code | Run Python, JavaScript or bash code |
write_file / read_file | Upload and read files (writing creates missing directories) |
list_files / delete_path | List a directory, delete a file or directory |
list_sandboxes / list_templates | See running and sleeping sandboxes and available templates |
set_timeout | Extend a sandbox's lifetime |
get_public_url | HTTPS address of a web app or API running in the sandbox |
pause_sandbox / resume_sandbox | Put a sandbox to sleep (files kept, programs stop, no compute billed) and wake it up – any command wakes it too. Sandboxes from the assistant fall asleep after their lifetime or 10 minutes without commands instead of being destroyed |
kill_sandbox | Destroy a sandbox (also a sleeping one) |
run_job / get_job_summary | Run a command as a background job and check on it later – detail: short (next step), full (complete record with all result files) or receipt (execution receipt with the exact template build and checksums – the signed version is available over the REST API, the Python SDK or in the portal). Also download_job_artifact, cancel_job, retry_job |
list_jobs | Your recent jobs or batches, newest first – filter by state, batch or time (since: 24h, 7d …), paged |
wait_jobs | Wait until a job or batch finishes – the assistant does not have to keep asking |
get_job_logs | A compact log digest by default: recognised test results, errors with context and the end of the log (mode=raw for raw bytes) |
run_batch / get_batch_summary / cancel_batch | Run many jobs at once with a concurrency and price limit, see the aggregated result |
get_budget | Your spending limits, spend and reservations |
get_compute_classes | Compute classes available to you and your default class |
If the assistant doesn't pass a sandbox id, the tools use the last sandbox it created in the conversation (and create one when there is none).
Sandboxes created over MCP fall asleep after their lifetime or 10 minutes without commands instead of being destroyed – see Sleep and wake. Command output, file contents and logs are returned to the assistant as data from the sandbox.