Quickstart

Run your first container in 5 minutes.

Prerequisites

An MCP-compatible client (Claude Code, Claude Desktop, or OpenAI Codex CLI)
A Contree API token

Getting an API Token

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

Installation

Step 1: Authenticate

contree-mcp reads the same auth.ini that contree-cli writes, so a single login covers both tools. Recommended: install contree-cli and run contree auth:

uv tool install contree-cli   # or: pip install contree-cli
contree auth                  # interactive setup

This writes ~/.config/contree/auth.ini (mode 0600). The MCP server picks it up automatically. If you prefer to write the file 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>

To switch between profiles later: contree auth switch <name>, or pass --profile <name> / CONTREE_PROFILE=<name> to contree-mcp.

Step 2: Configure Your MCP Client

Claude Code
Claude Desktop
OpenAI Codex CLI

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

Restart Claude Code or run /mcp to verify.

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"]
    }
  }
}

Add to ~/.codex/config.toml:

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

You can also pass credentials via environment variables (CONTREE_TOKEN, CONTREE_URL, CONTREE_PROJECT, CONTREE_PROFILE) or CLI flags (--token, --url, --project, --profile). These are useful for ephemeral overrides — but tokens passed via env may show up in process listings, so for routine use prefer the auth.ini profile written by contree auth.

Your First Container

Step 1: Check Available Images

{"tool": "list_images", "args": {"tag_prefix": "python", "limit": 5}}

If you don’t have any Python images, import one:

{"tool": "import_image", "args": {"registry_url": "docker://python:3.11-slim"}}

Response:

{
  "result_image": "abc123-def456-...",
  "state": "SUCCESS"
}

Step 2: Run a Command

{
  "tool": "run",
  "args": {
    "command": "python -c \"print('Hello from Contree!')\"",
    "image": "abc123-def456-..."
  }
}

Response:

{
  "exit_code": 0,
  "stdout": "Hello from Contree!\n",
  "state": "SUCCESS"
}

Step 3: Run with Local Files

First, sync your files:

{
  "tool": "rsync",
  "args": {
    "source": "/path/to/your/project",
    "destination": "/app",
    "exclude": ["__pycache__", ".git", ".venv"]
  }
}

Response:

{
  "directory_state_id": "ds_xyz789...",
  "stats": {"uploaded": 5, "cached": 10}
}

Then run with the synced files:

{
  "tool": "run",
  "args": {
    "command": "python /app/main.py",
    "image": "abc123-def456-...",
    "directory_state_id": "ds_xyz789..."
  }
}

What’s Next?

Concepts

Understand images, lineage, and async execution.

Patterns

Common workflows and best practices.

Tool Reference

Detailed parameters for all 15 tools.

Resources

MCP resources and guide sections.

Get Started

Inference

Observability

Post-training

Data Lab

Sandboxes

Teams & Access Management

Other Capabilities

Integrations

Prerequisites

Getting an API Token

Installation

Step 1: Authenticate

Step 2: Configure Your MCP Client

Your First Container

Step 1: Check Available Images

Step 2: Run a Command

Step 3: Run with Local Files

What’s Next?

Concepts

Patterns

Tool Reference

Resources

​Prerequisites

​Getting an API Token

​Installation

​Step 1: Authenticate

​Step 2: Configure Your MCP Client

​Your First Container

​Step 1: Check Available Images

​Step 2: Run a Command

​Step 3: Run with Local Files

​What’s Next?

Concepts

Patterns

Tool Reference

Resources

Prerequisites

Getting an API Token

Installation

Step 1: Authenticate

Step 2: Configure Your MCP Client

Your First Container

Step 1: Check Available Images

Step 2: Run a Command

Step 3: Run with Local Files

What’s Next?