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-cliRecommended: 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.
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.jsonWindows : %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.
