ConTree MCP Server

Run code in isolated cloud containers. ConTree gives AI agents secure sandboxed execution environments with full root access, network, and persistent images.

Why ConTree?

Fearless experimentation. Agents can:

• Run destructive commands (rm -rf /, dd, kernel exploits) - nothing escapes the sandbox
• Make mistakes freely - revert to any previous image UUID at zero cost
• Execute potentially dangerous user requests - ConTree IS the safe runtime for risky operations
• Break things on purpose - corrupt filesystems, crash kernels, test failure modes

Every container is isolated. Every image is immutable. Branching is cheap. Mistakes are free.

Quick Setup

1. Get an API Token

Contree is in Early Access. To get an API token, fill out the request form at contree.dev.

2. Create Config File

contree-mcp reads the same auth.ini that contree-cli writes, so a single login covers all contree-related tools.

Recommended: install contree-cli (see installation guide) and manage credentials with it rather than editing the file by hand:

contree auth --help  # add, switch, list, remove profiles

Default location: $XDG_CONFIG_HOME/contree/auth.ini (typically ~/.config/contree/auth.ini). Override the directory with CONTREE_HOME.

If you really need to write it by hand:

[DEFAULT]
profile = default

[profile:default]
type = iam
url = https://api.tokenfactory.nebius.com/sandboxes
token = <TOKEN HERE>
project = <NEBIUS PROJECT ID>

For the legacy JWT flow (contree.dev), use:

[profile:default]
type = jwt
url = https://contree.dev
token = <TOKEN HERE>

3. Configure Your MCP Client

Claude Code

claude mcp add --transport stdio contree -- $(which uvx) contree-mcp

Restart Claude Code or run /mcp to verify.

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.contree]
command = "uvx"
args = ["contree-mcp"]

Claude Desktop

Add to config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Note: You can alternatively pass credentials via environment variables (CONTREE_TOKEN, CONTREE_URL, CONTREE_PROJECT, CONTREE_PROFILE) in your MCP client config, but this is not recommended as tokens may appear in process listings.

Manual Installation

# Using uv
uv pip install contree-mcp

# Using pip
pip install contree-mcp

# Run manually (IAM auth)
contree-mcp --token YOUR_TOKEN --project YOUR_PROJECT

# Or pick a profile from ~/.config/contree/auth.ini
contree-mcp --profile staging

# HTTP mode (for network access)
contree-mcp --mode http --http-port 9452 --profile default

# Visit http://localhost:9452/ for interactive documentation with
# setup guides, tool reference, and best practices.

Container Installation (Alpine/Ubuntu/Debian)

These distros enable PEP 668, which protects the system Python from pip install mutations. Use an isolated tool installer:

# Recommended: isolated install, no PEP 668 conflicts
uv tool install contree-mcp
# or
pipx install contree-mcp

Both put contree-mcp on your PATH while keeping its dependencies in a private venv. uvx contree-mcp (used by the MCP-client snippets above) also works without installation since it spawns an ephemeral env per invocation.

pip install --break-system-packages contree-mcp

Configuration

Resolution priority for credentials: CLI flag > environment variable > profile in config.ini.

Available Tools

Command Execution

Image Management

File Transfer

Image Inspection

Operations

Documentation

Resource Templates

MCP resource templates expose image files and documentation directly via URIs. Fast operations, no VM required.

URI Examples:

• contree://image/abc-123-uuid/read/etc/passwd - Read file by image UUID
• contree://image/tag:alpine:latest/read/etc/os-release - Read file by tag
• contree://image/abc-123-uuid/ls/. - List root directory
• contree://image/tag:python:3.11/ls/usr/local/lib - List nested directory
• contree://image/abc-123-uuid/lineage - View image ancestry and children
• contree://guide/reference - Tool reference
• contree://guide/quickstart - Common workflow patterns

Guide Sections: workflow, reference, quickstart, state, async, tagging, errors

Examples

Prepare a Reusable Environment (Recommended First Step)

Step 1: Check for existing environment

// contree_list_images
{"tag_prefix": "common/python-ml"}

Step 2: If not found, build and tag it

// contree_import_image
{"registry_url": "docker://docker.io/python:3.11-slim"}

// contree_run (install packages)
{"command": "pip install numpy pandas scikit-learn", "image": "<result_image>", "disposable": false}

// contree_set_tag
{"image_uuid": "<result_image>", "tag": "common/python-ml/python:3.11-slim"}

Step 3: Use the prepared environment

// contree_run
{"command": "python train_model.py", "image": "tag:common/python-ml/python:3.11-slim"}

Run a command

contree_run:

{"command": "python -c 'print(\"Hello from ConTree!\")'", "image": "tag:python:3.11"}

Parallel Execution (Async Pattern)

Launch multiple instances simultaneously with wait: false, then poll for results:

contree_run (x3):

{"command": "python experiment_a.py", "image": "tag:python:3.11", "wait": false}
{"command": "python experiment_b.py", "image": "tag:python:3.11", "wait": false}
{"command": "python experiment_c.py", "image": "tag:python:3.11", "wait": false}

Each returns immediately with operation_id. Poll with contree_get_operation:

{"operation_id": "op-1"}

Trie-like Exploration Tree

Build branching structures where results become new source images.

contree_run - create branch point with disposable: false:

{"command": "pip install numpy pandas", "image": "tag:python:3.11", "disposable": false}

Returns result_image: "img-with-deps".

contree_run - branch into parallel experiments:

{"command": "python test_numpy.py", "image": "img-with-deps", "wait": false}
{"command": "python test_pandas.py", "image": "img-with-deps", "wait": false}

Sync Local Files to Container

contree_rsync - sync a project directory:

{
  "source": "/path/to/project",
  "destination": "/app",
  "exclude": ["__pycache__", "*.pyc", ".git", "node_modules"]
}

Returns directory_state_id: "ds_abc123".

contree_run - run with injected files:

{
  "command": "python /app/main.py",
  "image": "tag:python:3.11",
  "directory_state_id": "ds_abc123"
}

List images

contree_list_images:

{"tag_prefix": "python"}

Read a file (Resource Template)

Use the contree_image_file resource template:

contree://image/tag:busybox:latest/read/etc/passwd

Import an image

Step 1: Authenticate with registry (first time only)

// contree_registry_token_obtain - opens browser for PAT creation
{"registry_url": "docker://docker.io/alpine:latest"}

// contree_registry_auth - validate and store credentials
{"registry_url": "docker://docker.io/alpine:latest", "username": "myuser", "token": "dckr_pat_xxx"}

Step 2: Import the image

// contree_import_image
{"registry_url": "docker://docker.io/alpine:latest"}

To make it reusable, tag after importing:

// contree_set_tag
{"image_uuid": "<result_image>", "tag": "common/base/alpine:latest"}

Track Image Lineage

View parent-child relationships and navigate image history using the contree_image_lineage resource:

contree://image/abc-123-uuid/lineage

Returns:

{
  "image": "abc-123-uuid",
  "parent": {"image": "parent-uuid", "command": "pip install numpy", "exit_code": 0},
  "children": [{"image": "child-uuid", "command": "python test.py", ...}],
  "ancestors": [/* parent chain up to root */],
  "root": {"image": "root-uuid", "registry_url": "docker://python:3.11", "is_import": true},
  "depth": 2,
  "is_known": true
}

Use this to rollback to any ancestor or understand how an image was created.

Download a build artifact

contree_download:

{"image": "img-build-result", "path": "/app/dist/binary", "destination": "./binary", "executable": true}

Dependencies

• mcp - Model Context Protocol SDK
• httpx - Async HTTP client
• argclass - Argument parsing
• aiosqlite - Async SQLite database
• pydantic - Data validation

Development

Requirements: Python 3.10+

git clone https://github.com/nebius/contree-mcp.git
cd contree-mcp
make install

Development Workflow

make check     # lint + typecheck + tests (run before pushing)
make test      # tests only (quiet)
make format    # auto-fix formatting and lint
make help      # full target list

When making changes:

1. Edit code in contree_mcp/
2. Run make check — must pass before opening a PR
3. Update documentation if behavior changes:
   • README.md — user-facing docs, examples, tool descriptions
   • llm.txt — shared context for AI agents (architecture, class hierarchy, internals)

Without make

If you'd rather not use make, the underlying uv run commands are:

uv sync --group dev                                    # install
uv run pytest tests/ -q                                # test
uv run ruff check contree_mcp                          # lint
uv run ruff format contree_mcp                         # format
uv run mypy contree_mcp                                # typecheck
uv run pytest tests/tools/test_run_command.py -v       # single test file

Testing GitHub Actions Locally

Use act to run GitHub Actions workflows locally before pushing:

# Install act
brew install act        # macOS
sudo pacman -S act      # Arch Linux
sudo apt install act    # Debian/Ubuntu (via nix or manual install)

# List available jobs
act -l

# Run lint and typecheck jobs (fast)
act -j lint
act -j typecheck

# Run tests for Linux only (act simulates Linux)
act -j test --matrix os:ubuntu-latest

# Run specific Python version
act -j test --matrix os:ubuntu-latest --matrix python-version:3.12

# Run all jobs sequentially (stop on first failure)
act -j lint && act -j typecheck && act -j test --matrix os:ubuntu-latest

# Dry run (show what would execute)
act -n

Note: act uses Docker containers that simulate Linux runners. macOS/Windows matrix jobs will run in Linux containers, so use --matrix os:ubuntu-latest for accurate local testing.

Copyright

Nebius B.V. 2026, Licensed under the Apache License, Version 2.0 (see "LICENSE" file).