What It Is

ConTree MCP exposes ConTree's sandboxed execution platform to any MCP-compatible client: Claude Code, Claude Desktop, OpenAI Codex, and others. Agents get full root access inside isolated microVMs, can move files in and out, and keep clean snapshots of every execution. Every image is immutable, every run can produce a new child image, and rollback is just a UUID reference away.

What Agents Can Do

The server exposes tools grouped around five capabilities:

Execute code - Run arbitrary commands in isolated containers with stdout/stderr capture, environment variables, file injection, and configurable timeouts. Runs can be synchronous or async.

Manage images - Import base images from OCI registries (Docker Hub, GitHub, GitLab), list and inspect existing images, and tag frequently-used environments for instant reuse.

Transfer files - Upload single files or rsync entire project directories into containers. Download build artifacts and outputs back to the local filesystem. Smart caching ensures only changed files are transferred.

Inspect without executing - Browse an image's filesystem and read file contents without spinning up a VM. Instant and free.

Run in parallel - Launch multiple operations with wait=false, then collect results with wait_operations. Race competing approaches from the same checkpoint and pick the winner.

Setup

Install and register in one line:

claude mcp add --transport stdio contree -- uvx contree-mcp --token YOUR_TOKEN

For Claude Desktop, add to your config:

{
  "mcpServers": {
    "contree": {
      "command": "uvx",
      "args": ["contree-mcp", "--token", "YOUR_TOKEN"]
    }
  }
}

Or run standalone in HTTP mode with an interactive tool reference at http://localhost:9452/:

pip install contree-mcp
contree-mcp --mode http --http-port 9452 --token YOUR_TOKEN

How Agents Use It

A typical workflow has three steps:

1. Check for a prepared environment.

list_images(tag_prefix="common/")

2. Prepare one if needed. Import a base image, install dependencies, and tag the result for reuse.

import_image(registry_url="docker://python:3.11-slim")
run(command="pip install numpy pandas", image="<uuid>", disposable=false)
set_tag(image_uuid="<result>", tag="common/python-ml/python:3.11-slim")

3. Execute the task. Use the tagged image directly.

run(command="python train.py", image="tag:common/python-ml/python:3.11-slim")

Because images are immutable, the agent can branch from any checkpoint to try competing fixes in parallel, then keep the branch that passes tests and discard the rest.

Branching In Practice

Agents often need to verify multiple hypotheses. ConTree MCP makes that cheap:

# Install dependencies once (disposable=false saves the image)
run(command="pip install pytest", image=base, disposable=false) -> uuid_with_deps

# Branch: try two fixes from the same state
run(command="python fix_a.py && pytest", image=uuid_with_deps, wait=false) -> op1
run(command="python fix_b.py && pytest", image=uuid_with_deps, wait=false) -> op2

# Wait for both, pick the winner
wait_operations(operation_ids=[op1, op2])

No manual cleanup, no hidden state drift. Each branch starts from a clean, identical snapshot.

Cost Awareness

Not every operation needs a VM. The server distinguishes between:

  • VM operations (2-5s): run, import_image
  • Free operations (instant): list_images, get_image, set_tag, list_files, read_file, upload, download, rsync

Agents are guided to prefer free inspection tools over run("ls") or run("cat"), and to reuse tagged images instead of re-importing.

Takeaway

ConTree MCP brings ConTree's branching execution model into the MCP ecosystem. It gives coding agents a safe, fast way to explore, compare, and recover, with a small API surface, built-in cost awareness, and workflows that map naturally to how agents already think: try, branch, verify, keep the best result.