Connect a client¶

Transport: stdio · Config format: mcpServers map

The Aetelier MCP server speaks MCP over stdio: a client launches the atelier-mcp binary as a subprocess and exchanges JSON-RPC over its standard input and output. Every client below registers the same launch command and the same environment map — only the file the config lives in differs.

Before you connect

The atelier-mcp binary, built with cargo build --release (it lands at target/release/atelier-mcp). Use its absolute path in the config.
An API key you create in the webapp (Settings → Security). It is the value for ATELIER_OVERSEER_TOKEN and ATELIER_OVERDEX_TOKEN, and it lets the server act as you.

Configuration fields¶

The server addresses four domains, each its own service, so the config carries a URL per domain plus the credentials each one needs. The defaults are the localhost values that match the platform's host-published docker ports — set the two token fields to your API key and leave the rest at their defaults for a local platform.

Field	Default	Meaning
`ATELIER_OVERSEER_URL`	`http://localhost:8000`	Collectors service (deploy, list, status, command, stop)
`ATELIER_OVERSEER_TOKEN`	`dev-token`	Your API key, presented to overseer as you
`ATELIER_OVERDEX_URL`	`http://localhost:8210`	Fit & serve service (datasets, Hawkes fits, forecasts)
`ATELIER_OVERDEX_TOKEN`	`dev-token`	Your API key, presented to overdex as you
`ATELIER_OVERWATCH_URL`	`http://localhost:8310`	Governance service (catalog, scorecards, datasets)
`ATELIER_COLOCATION_URL`	`http://localhost:8123`	Pulsar colocation oracle (ClickHouse)
`ATELIER_COLOCATION_DB`	`pulsar`	Colocation database
`ATELIER_COLOCATION_USER`	`default`	Read-only colocation user
`ATELIER_COLOCATION_PASSWORD`	`pulsar_dev`	Read-only colocation password
`RUST_LOG`	`warn`	Log level, written to stderr

When the server runs inside the platform's docker networks, point the URLs at the service DNS names instead: http://overseer:8000, http://overdex-server:8210, http://overwatch:8310, http://pulsar-db:8123.

Authentication¶

The real credential is an API key you create in the webapp under Settings → Security. It is account-scoped and time-limited. In production it is the value for both ATELIER_OVERSEER_TOKEN and ATELIER_OVERDEX_TOKEN — the two domains that act as you. dev-token is only the local development default that a freshly booted platform accepts.

The colocation oracle authenticates separately, with a read-only ClickHouse user and password (ATELIER_COLOCATION_USER / ATELIER_COLOCATION_PASSWORD).

Handle the key like a password

Keep the API key in the client's config file, out of shared snippets and version control. If it is exposed, revoke it from the same page (Settings → Security) and issue a new one.

Client setup¶

Claude DesktopClaude CodeCursorVS CodeGeneric

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "atelier": {
      "command": "/absolute/path/to/target/release/atelier-mcp",
      "env": {
        "ATELIER_OVERSEER_URL": "http://localhost:8000",
        "ATELIER_OVERSEER_TOKEN": "your-api-key",
        "ATELIER_OVERDEX_URL": "http://localhost:8210",
        "ATELIER_OVERDEX_TOKEN": "your-api-key",
        "ATELIER_OVERWATCH_URL": "http://localhost:8310",
        "ATELIER_COLOCATION_URL": "http://localhost:8123",
        "ATELIER_COLOCATION_DB": "pulsar",
        "ATELIER_COLOCATION_USER": "default",
        "ATELIER_COLOCATION_PASSWORD": "pulsar_dev",
        "RUST_LOG": "warn"
      }
    }
  }
}

Restart Claude Desktop. The atelier tools appear in the tool picker.

Register the server from the CLI, passing one --env flag per variable:

claude mcp add atelier \
  --env ATELIER_OVERSEER_URL=http://localhost:8000 \
  --env ATELIER_OVERSEER_TOKEN=your-api-key \
  --env ATELIER_OVERDEX_URL=http://localhost:8210 \
  --env ATELIER_OVERDEX_TOKEN=your-api-key \
  --env ATELIER_OVERWATCH_URL=http://localhost:8310 \
  --env ATELIER_COLOCATION_URL=http://localhost:8123 \
  --env ATELIER_COLOCATION_DB=pulsar \
  --env ATELIER_COLOCATION_USER=default \
  --env ATELIER_COLOCATION_PASSWORD=pulsar_dev \
  --env RUST_LOG=warn \
  -- /absolute/path/to/target/release/atelier-mcp

Or add it to .mcp.json at the project root:

{
  "mcpServers": {
    "atelier": {
      "command": "/absolute/path/to/target/release/atelier-mcp",
      "env": {
        "ATELIER_OVERSEER_URL": "http://localhost:8000",
        "ATELIER_OVERSEER_TOKEN": "your-api-key",
        "ATELIER_OVERDEX_URL": "http://localhost:8210",
        "ATELIER_OVERDEX_TOKEN": "your-api-key",
        "ATELIER_OVERWATCH_URL": "http://localhost:8310",
        "ATELIER_COLOCATION_URL": "http://localhost:8123",
        "ATELIER_COLOCATION_DB": "pulsar",
        "ATELIER_COLOCATION_USER": "default",
        "ATELIER_COLOCATION_PASSWORD": "pulsar_dev",
        "RUST_LOG": "warn"
      }
    }
  }
}

Confirm registration with claude mcp list.

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "atelier": {
      "command": "/absolute/path/to/target/release/atelier-mcp",
      "env": {
        "ATELIER_OVERSEER_URL": "http://localhost:8000",
        "ATELIER_OVERSEER_TOKEN": "your-api-key",
        "ATELIER_OVERDEX_URL": "http://localhost:8210",
        "ATELIER_OVERDEX_TOKEN": "your-api-key",
        "ATELIER_OVERWATCH_URL": "http://localhost:8310",
        "ATELIER_COLOCATION_URL": "http://localhost:8123",
        "ATELIER_COLOCATION_DB": "pulsar",
        "ATELIER_COLOCATION_USER": "default",
        "ATELIER_COLOCATION_PASSWORD": "pulsar_dev",
        "RUST_LOG": "warn"
      }
    }
  }
}

The tools appear under Settings → MCP.

Add an mcp.json entry (Command Palette → MCP: Add Server, or edit the file directly). VS Code nests servers under a servers key:

{
  "servers": {
    "atelier": {
      "type": "stdio",
      "command": "/absolute/path/to/target/release/atelier-mcp",
      "env": {
        "ATELIER_OVERSEER_URL": "http://localhost:8000",
        "ATELIER_OVERSEER_TOKEN": "your-api-key",
        "ATELIER_OVERDEX_URL": "http://localhost:8210",
        "ATELIER_OVERDEX_TOKEN": "your-api-key",
        "ATELIER_OVERWATCH_URL": "http://localhost:8310",
        "ATELIER_COLOCATION_URL": "http://localhost:8123",
        "ATELIER_COLOCATION_DB": "pulsar",
        "ATELIER_COLOCATION_USER": "default",
        "ATELIER_COLOCATION_PASSWORD": "pulsar_dev",
        "RUST_LOG": "warn"
      }
    }
  }
}

Start the server from the MCP view, then use the tools from Chat.

Any MCP client that launches a stdio server accepts the same shape: a command plus an environment map.

{
  "mcpServers": {
    "atelier": {
      "command": "/absolute/path/to/target/release/atelier-mcp",
      "env": {
        "ATELIER_OVERSEER_URL": "http://localhost:8000",
        "ATELIER_OVERSEER_TOKEN": "your-api-key",
        "ATELIER_OVERDEX_URL": "http://localhost:8210",
        "ATELIER_OVERDEX_TOKEN": "your-api-key",
        "ATELIER_OVERWATCH_URL": "http://localhost:8310",
        "ATELIER_COLOCATION_URL": "http://localhost:8123",
        "ATELIER_COLOCATION_DB": "pulsar",
        "ATELIER_COLOCATION_USER": "default",
        "ATELIER_COLOCATION_PASSWORD": "pulsar_dev",
        "RUST_LOG": "warn"
      }
    }
  }
}

Launch the binary as a subprocess and exchange JSON-RPC over its stdio.

Verify the connection¶

Once registered, ask the client to call platform_health first. It reports the liveness of each backing service, so you know the whole platform is reachable before doing real work:

{
  "overseer": "ok",
  "overdex_server": "ok",
  "overwatch": "ok",
  "pulsar_clickhouse": "ok"
}

Each field reads ok when its service answers. Any other value carries the reason — a status code or an error string — so you can tell exactly which domain is not ready.