Docs / MCP Server
MODEL CONTEXT PROTOCOL · STDIO JSON-RPC 2.0

Give Claude & Cursor
instant microVMs, DBs & apps.

uncage-mcp exposes 9 structured MCP tools over stdio—letting AI coding assistants boot isolated sandboxes, execute tests, live-fork state, pause to $0/hr, provision PostgreSQL 17, and deploy live HTTPS previews directly from chat.

CLIENT CONFIGURATION

Drop-in JSON for Claude Desktop, Cursor & MCP hosts.

claude_desktop_config.json (native binary) RECOMMENDED
{
  "mcpServers": {
    "uncage": {
      "command": "uncage-mcp",
      "env": {
        "UNCAGE_API_URL": "https://api.uncage.sh",
        "UNCAGE_API_KEY": "ucg_live_your_api_key_here"
      }
    }
  }
}
macOS path: ~/Library/Application Support/Claude/claude_desktop_config.json
.cursor/mcp.json (npx zero-install) CURSOR / WINDSURF
{
  "mcpServers": {
    "uncage": {
      "command": "npx",
      "args": ["-y", "@uncage/mcp-server"],
      "env": {
        "UNCAGE_API_URL": "https://api.uncage.sh",
        "UNCAGE_API_KEY": "ucg_live_your_api_key_here"
      }
    }
  }
}
Place in workspace .cursor/mcp.json or global ~/.cursor/mcp.json
COMPLETE TOOL CATALOG (9 TOOLS)

All 9 tools exposed by uncage-mcp.

Protocol: MCP 2024-11-05 · Transport: stdio
01

uncage_create_sandbox

Sandbox

Create an instant isolated AI agent sandbox or Ubuntu cloud desktop with automatic sleep ($0/hr idle compute).

Required: project_id name
Optional: image region vcpu memory_mb disk_gb idle_timeout_seconds desktop env
{
  "name": "uncage_create_sandbox",
  "arguments": {
    "project_id": "proj_agents",
    "name": "swe-agent-01",
    "region": "us-east",
    "vcpu": 2,
    "memory_mb": 4096,
    "idle_timeout_seconds": 120
  }
}
02

uncage_exec

Execution

Execute a shell or binary command inside a running workload and return stdout, stderr, and exit_code.

Required: workload_id cmd
Optional: timeout_sec
{
  "name": "uncage_exec",
  "arguments": {
    "workload_id": "wl_01j9x7",
    "cmd": ["pytest", "-q", "tests/"],
    "timeout_sec": 60
  }
}
03

uncage_pause_sandbox

Sandbox

Pause a running sandbox to durable snapshot storage with RAM and disk preserved ($0.00/hr compute while sleeping).

Required: workload_id
{
  "name": "uncage_pause_sandbox",
  "arguments": { "workload_id": "wl_01j9x7" }
}
04

uncage_resume_sandbox

Sandbox

Wake a sleeping sandbox in sub-second time with all running processes, memory, and filesystem state intact.

Required: workload_id
{
  "name": "uncage_resume_sandbox",
  "arguments": { "workload_id": "wl_01j9x7" }
}
05

uncage_fork_sandbox

Sandbox

Create a live copy-on-write memory + disk fork (~180ms) of a running sandbox for parallel agent branching or A/B tests.

Required: workload_id
Optional: name
{
  "name": "uncage_fork_sandbox",
  "arguments": {
    "workload_id": "wl_01j9x7",
    "name": "swe-agent-01-hypothesis-b"
  }
}
06

uncage_list_workloads

Workspace

List active and sleeping workloads for your organization, optionally scoped to a single project_id.

Required: none
Optional: project_id
{
  "name": "uncage_list_workloads",
  "arguments": { "project_id": "proj_agents" }
}
07

uncage_list_nodes

Workspace

Inspect available regional compute capacity, headroom, and health status across global regions.

Required: none
{
  "name": "uncage_list_nodes",
  "arguments": {}
}
08

uncage_create_database

Database

Provision a managed PostgreSQL 17, MySQL 8.4, or Redis 7 database on dedicated NVMe storage with private project DNS.

Required: project_id name
Optional: engine image region vcpu memory_mb disk_gb env
{
  "name": "uncage_create_database",
  "arguments": {
    "project_id": "proj_agents",
    "name": "pg-eval",
    "engine": "postgres",
    "region": "us-east",
    "vcpu": 2,
    "memory_mb": 4096,
    "disk_gb": 20
  }
}
09

uncage_deploy_app

Apps

Deploy a web app or backend API from an OCI image with instant HTTPS routing and optional scale-to-zero.

Required: project_id name image
Optional: expose_port region vcpu memory_mb disk_gb idle_timeout_seconds command env
{
  "name": "uncage_deploy_app",
  "arguments": {
    "project_id": "proj_agents",
    "name": "preview-web",
    "image": "ghcr.io/acme/web:pr-42",
    "expose_port": 3000,
    "region": "us-east",
    "idle_timeout_seconds": 300
  }
}
MCP SERVER FAQ

Common questions about connecting AI clients to uncage-mcp.

01 Which AI clients support uncage-mcp?
uncage-mcp implements the standard Model Context Protocol (JSON-RPC 2.0 over stdio, protocol version 2024-11-05) and works out of the box with Claude Desktop, Cursor, Windsurf, Claude Code, and any custom MCP host.
02 How do I keep agent costs bounded when giving an LLM MCP access?
Always pass idle_timeout_seconds (for example, 120 or 300 seconds) when creating sandboxes or apps, and set an account spend limit in your dashboard. Sleeping workloads automatically bill $0.00/hr.
03 Can an MCP agent create both a sandbox and a Postgres database in the same session?
Yes. The agent can call uncage_create_database followed by uncage_create_sandbox in the same project_id, then run migrations and tests over private internal DNS via uncage_exec.
AGENT-READY INFRASTRUCTURE

Generate an API key and attach uncage-mcp today.

Give Claude, Cursor, or your autonomous agent fleet sub-200ms sandboxes, PostgreSQL 17, and live HTTPS previews.

✓ $10 starter credit on signup
✓ Strictly $0.00/hr compute when sleeping
✓ Sub-second boot across 4 global regions