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
401withWWW-Authenticate: Bearerand{"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_downloadwrites 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:
Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):
VS Code nests servers under a servers key in mcp.json:
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.
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.
Confirm registration with claude mcp list.
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:
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.