Skip to content

Connect a client

Hosted: https://aetelier.xyz/mcp (Streamable HTTP) · Local: the aetelier-mcp binary (stdio) · Auth: your API key

Both ways expose the same 22 tools and act as you through your API key. The hosted endpoint needs nothing installed. The local binary runs next to your client and reaches the platform over HTTPS.

Before you connect

An API key you create in the webapp under Settings → Security. It is account-scoped and time-limited, and it is the only credential either way needs.

Hosted endpoint

Point a client that supports Streamable HTTP at https://aetelier.xyz/mcp and send the key on every request as Authorization: Bearer <your-api-key>.

  • A request without the header answers 401 with WWW-Authenticate: Bearer and {"ok": false, "code": "API_KEY_MISSING", ...}.
  • The endpoint is stateless: every request stands alone, and no session id is issued.
  • Each response streams as server-sent events with a keep-alive every 15 seconds, so a long fit holds the connection open until its result arrives.
  • clarion_download writes nothing on the server. It returns file URLs and the commands that fetch and check them, see the tool reference.

Clients that connect to remote servers only through an OAuth sign-in cannot send an API key header yet. Use the local binary with them.

claude mcp add --transport http aetelier https://aetelier.xyz/mcp \
  --header "Authorization: Bearer your-api-key"

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

{
  "mcpServers": {
    "aetelier": {
      "type": "http",
      "url": "https://aetelier.xyz/mcp",
      "headers": { "Authorization": "Bearer your-api-key" }
    }
  }
}

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

{
  "mcpServers": {
    "aetelier": {
      "url": "https://aetelier.xyz/mcp",
      "headers": { "Authorization": "Bearer your-api-key" }
    }
  }
}

VS Code nests servers under a servers key in mcp.json:

{
  "servers": {
    "aetelier": {
      "type": "http",
      "url": "https://aetelier.xyz/mcp",
      "headers": { "Authorization": "Bearer your-api-key" }
    }
  }
}

Any Streamable HTTP client: POST JSON-RPC to https://aetelier.xyz/mcp with Content-Type: application/json, Accept: application/json, text/event-stream and Authorization: Bearer your-api-key.

curl -sN https://aetelier.xyz/mcp \
  -H "Authorization: Bearer $AETELIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Local binary

Download the archive for your platform from the latest release: aarch64-apple-darwin (Apple Silicon), x86_64-unknown-linux-musl or aarch64-unknown-linux-musl. Each archive comes with a .sha256 file to compare against shasum -a 256 of the archive. Unpack it and use the absolute path of aetelier-mcp in your client's config. Building from source with cargo build --release gives the same binary.

Configuration fields

Field Meaning
AETELIER_API_KEY Your API key. Required
AETELIER_URL Platform base URL, default https://aetelier.xyz
AETELIER_CLARION_DIR Where clarion_download writes records, default clarion-records
RUST_LOG Log level, written to stderr (default warn)

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

{
  "mcpServers": {
    "aetelier": {
      "command": "/absolute/path/to/aetelier-mcp",
      "env": { "AETELIER_API_KEY": "your-api-key" }
    }
  }
}

Restart the app. The aetelier tools appear in the tool picker.

claude mcp add aetelier --env AETELIER_API_KEY=your-api-key \
  -- /absolute/path/to/aetelier-mcp

Confirm registration with claude mcp list.

{
  "mcpServers": {
    "aetelier": {
      "command": "/absolute/path/to/aetelier-mcp",
      "env": { "AETELIER_API_KEY": "your-api-key" }
    }
  }
}
{
  "servers": {
    "aetelier": {
      "type": "stdio",
      "command": "/absolute/path/to/aetelier-mcp",
      "env": { "AETELIER_API_KEY": "your-api-key" }
    }
  }
}

Any MCP client that launches a stdio server accepts a command plus an environment map:

{
  "mcpServers": {
    "aetelier": {
      "command": "/absolute/path/to/aetelier-mcp",
      "env": { "AETELIER_API_KEY": "your-api-key" }
    }
  }
}

Authentication

The key is the only credential, for every tool. A missing, wrong, revoked or expired key makes each tool return {"ok": false, ...} with a 401 reason, and platform_health shows it as api_key.

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.

Verify the connection

Once registered, ask the client to call platform_health first. It checks the platform from the MCP server with your key: the overseer's liveness, the key itself, and one read each from fit & serve, deploy-prep and colocation:

{
  "overseer": "ok",
  "api_key": "ok",
  "overdex_server": "ok",
  "overwatch": "ok",
  "overplex": "ok"
}

Each field reads ok when that check passes. Any other value carries the reason, a status code or an error string, so you can tell exactly what is not ready. Without a key, the local binary reports the keyed checks as skipped: no API key.