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: Create Config File

Store your credentials in ~/.config/contree/mcp.ini:

[DEFAULT]
url = https://contree.dev/
token = <TOKEN HERE>

Step 2: Configure Your MCP Client

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

Note

Alternatively, you can pass credentials via environment variables (CONTREE_MCP_TOKEN, CONTREE_MCP_URL) in your MCP client config, but this is not recommended as tokens may appear in process listings.

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.

Concepts
Patterns

Common workflows and best practices.

Patterns
Tool Reference

Detailed parameters for all 15 tools.

Tools Reference
Resources

MCP resources and guide sections.

Resources