Skip to content

Worked examples

Server: aetelier-mcp · Form: natural-language ask → tool sequence → results

Each flow is a full engagement: what you ask the client, the tools it drives to satisfy the ask, and the results it reads back between steps. You speak in natural language; the client picks the tools and chains them, reading each result before the next and adapting as it goes. Results are illustrative and abridged — live values vary.

Health first, cleanup last

A robust flow opens with platform_health and, for a deploy, closes with stop_collector. The flows below assume a reachable platform.

Errors are results, not failures

A backend error comes back as {"ok": false, "error": "..."}, with code and docs_url when the backend sent them — an ordinary tool result the client reads and adapts to in the same loop. Flow 2 shows this: a non-converged fit returns a 400 and becomes a looser-tolerance refit.


Flow 1 — Deploy a collector and confirm data is landing

Ask — "Stand up a Binance BTC spot collector in a low-latency region and tell me once it's actually producing data."

This is a remote bring-your-own deploy: deploy_collector registers the service and mints an agent JWT, and you run your own agent against the gateway with that JWT. The client drives:

platform_health → list_cex_options → query_colocation → deploy_collector → collector_health → stop_collector

Step 1 — confirm the platform answers

{ "tool": "platform_health", "arguments": {} }
{ "overseer": "ok", "api_key": "ok", "overdex_server": "ok", "overwatch": "ok", "overplex": "ok" }

Step 2 — resolve the venue and its native symbol format

The client consults the deployable options before it commits to a symbol string, since each venue names symbols differently.

{ "tool": "list_cex_options", "arguments": {} }
{
  "venues": [
    {
      "exchange": "binance",
      "label": "Binance",
      "symbol_format": "concatenated uppercase",
      "symbol_example": "BTCUSDT",
      "market_types": ["spot"],
      "orderbook_depths": [5, 10, 20, 50, 100, 500, 1000],
      "default_orderbook_depth": 50,
      "datatypes": [
        { "name": "orderbook", "available": true },
        { "name": "trades", "available": true }
      ]
    }
  ]
}

Binance names BTC spot as BTCUSDT, supports spot, and offers depth 50.

Step 3 — pick the region

{ "tool": "query_colocation", "arguments": { "exchange": "binance" } }
{
  "count": 1,
  "exchanges": [
    { "exchange": "binance", "region": "ap-northeast-1", "score": 0.96 }
  ]
}

Step 4 — register the remote collector

{
  "tool": "deploy_collector",
  "arguments": {
    "exchange": "binance",
    "symbols": ["BTCUSDT"],
    "market_type": "spot",
    "region": "ap-northeast-1"
  }
}
{
  "service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84",
  "binding_id": "cfb7688a-2d3f-4e91-8b6c-15a9e4f07d23",
  "gateway_url": "https://gateway.aetelier.xyz",
  "token": "your-agent-jwt"
}

The deploy returns the service_id, the binding_id, the gateway URL, and an agent JWT. Nothing is running yet: this is a bring-your-own collector, so you launch the agent yourself, pointing it at the returned gateway URL and passing the JWT.

Step 5 — run your own agent against the gateway

Set AETELIER_GATEWAY_URL to the deploy's gateway_url and AETELIER_TOKEN to its token. The agent reads the binding and service ids from the JWT's claims, so neither is a separate variable. The webapp's fleet view shows this command for the binding, with a freshly minted token:

docker run -d --pull always --restart unless-stopped --name aetelier-agent-binance-orderbook-cfb7 \
  -v "$HOME/aetelier-data:/home/agent" \
  -e AETELIER_GATEWAY_URL="https://gateway.aetelier.xyz" \
  -e AETELIER_TOKEN=your-agent-jwt \
  -e RUST_LOG=info \
  ghcr.io/aetelierxyz/aetelier-agent:latest

The full variable contract is in aetelier-agent → Environment variables.

The JWT is a credential scoped to this binding. Treat it like a password: keep it out of shared configs and version control.

Step 6 — confirm data is landing

A fresh deploy has no lake rows for the first few minutes, so collector_health leads with liveness and reads starting rather than reporting a failure.

Just after the agent starts:

{ "tool": "collector_health", "arguments": { "service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84" } }
{
  "service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84",
  "verdict": "starting",
  "liveness": { "connected": true, "heartbeat_age_s": 4, "ws_latency_ms": null },
  "landing": { "rows_last_5m": 0, "total_rows": 0,
               "expected_first_data_by": "2026-07-04T18:05:00Z" }
}

A few minutes later, once rows land:

{ "tool": "collector_health", "arguments": { "service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84" } }
{
  "service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84",
  "verdict": "healthy",
  "liveness": { "connected": true, "heartbeat_age_s": 3, "ws_latency_ms": null },
  "landing": { "rows_last_5m": 8421, "total_rows": 33110, "last_row_age_s": 2 }
}

The verdict flips to healthy once fresh rows land, and the client tells you data is flowing.

Step 7 — tear it down

{ "tool": "stop_collector", "arguments": { "service_id": "63060972-4c1e-4b8a-9f2d-7a5e0c3b1d84" } }
{
  "agent_id": "5b0e2c71-9a44-4f3e-8d16-c2a7f90b3e58",
  "binding_id": "cfb7688a-2d3f-4e91-8b6c-15a9e4f07d23",
  "session_id": "e41d9a03-6c2b-4f87-a5e9-0b3c7d18f246",
  "command_id": "9d7f3b2e-1a65-4c08-b4f3-6e2a8c05d917"
}

The stop is accepted at once and returns the release command. The service reads stopping until the agent acknowledges the release, then stopped.

Stop the collector when you are done to release the binding; a running collector draws data units once per UTC day. Between deploy and stop you can pause and resume the task with collector_command (task_pause, task_resume).


Flow 2 — Fit and forecast a model

Ask — "Fit a Hawkes model to Kraken ETH trades and forecast the next 10 events."

This flow adapts mid-loop: the first fit does not converge at the default tolerance, so the client reads the error and refits with a looser one. The client drives:

list_datasets → fit_pricing → fit_hawkes → get_fit → forecast_fit

Step 1 — pick a dataset

Hawkes fits want an event stream, so the client picks a trades dataset. fit_recommended marks a trades set in the size band a fit converges on well.

{ "tool": "list_datasets", "arguments": {} }
[
  { "dataset_id": "9f3a61c2d40b7e85", "venue": "kraken", "symbol": "ETH-USD",
    "data_type": "trades", "n_events": 702, "fit_recommended": true }
]

Step 2 — check the fit price

A fit draws compute units, and only when it converges. The client reads the price and reports it before it runs one.

{ "tool": "fit_pricing", "arguments": {} }
{ "hawkes_fit_cost": {cost}, "token_kind": "compute" }

hawkes_fit_cost is the price in compute units, the catalog's action_rates.hawkes_fit_compute. The balance is checked against it before the fit starts; if it is short, fit_hawkes returns a 402 and runs nothing. See Units and the 402 error.

Step 3 — first fit (does not converge)

{ "tool": "fit_hawkes", "arguments": { "dataset_id": "9f3a61c2d40b7e85" } }
{
  "ok": false,
  "error": "<service> 400: validation error: estimation did not produce a usable result: Not converged after 50000 iterations (gradient norm = 3.418207e4)"
}

The 400 is an ordinary result, and nothing was charged. Not converged after is the signal to raise tolerance above the server default of 50. A 402 is a different case: no tolerance clears it, so the client stops and reports it (Reading a 402).

Step 4 — refit with a looser tolerance

{
  "tool": "fit_hawkes",
  "arguments": { "dataset_id": "9f3a61c2d40b7e85", "tolerance": 500 }
}
{
  "fit_id": "7c21e0a4-5b8f-4d0e-9a63-2f1c8b7d4e10",
  "config": { "tolerance": 500, "max_iter": 50000, "train_ratio": 0.8 },
  "parameters": { "mu": 0.00017, "alpha": 0.0042, "beta": 0.0231 },
  "diagnostics": { "converged": true, "branching_ratio": 0.182, "iterations": 1843 },
  "baseline": { "lr_reject_h0": true },
  "data": { "n_events_train": 561 }
}

The refit converged, so it draws the fit price. baseline.lr_reject_h0 is true: the likelihood-ratio test rejects a plain Poisson model, and a branching ratio of 0.182 says the series is mildly self-exciting. If it still had not converged, the client would raise tolerance again.

Step 5 — read the full fit

fit_hawkes omits the chart series to keep the result small. The client fetches the full artifact — parameters, diagnostics, and series — with get_fit.

{ "tool": "get_fit", "arguments": { "fit_id": "7c21e0a4-5b8f-4d0e-9a63-2f1c8b7d4e10" } }
{
  "fit_id": "7c21e0a4-5b8f-4d0e-9a63-2f1c8b7d4e10",
  "diagnostics": { "converged": true, "branching_ratio": 0.182 },
  "series": { "intensity": [ ], "residual_ecdf": [ ], "residual_qq": [ ] }
}

Step 6 — forecast from the fit

{
  "tool": "forecast_fit",
  "arguments": { "fit_id": "7c21e0a4-5b8f-4d0e-9a63-2f1c8b7d4e10", "n_forecast": 10 }
}
{
  "fit_id": "7c21e0a4-5b8f-4d0e-9a63-2f1c8b7d4e10",
  "seed": 42,
  "mc_paths": 500,
  "deterministic": false,
  "n_forecast": 10,
  "points": [
    { "index": 0, "gap_ms": 3920, "gap_p25_ms": 1180, "gap_p75_ms": 6710 },
    { "index": 9, "gap_ms": 48183, "gap_p25_ms": 37950, "gap_p75_ms": 59420 }
  ]
}

Each point's gap_ms is the median cumulative gap since the end of the training data, with gap_p25_ms and gap_p75_ms as the band; the reply above shows the first and last of the 10 points. The client reports the 10th event near 48 seconds out. The same seed gives the same forecast; raise mc_paths to cut Monte-Carlo noise in the band.


Flow 3 — Audit an existing stream

Ask — "How complete is the Coinbase BTC/USDT order book?"

A short two-step read: the client resolves the stream in the governance catalog, then scores it. Governance reads draw no units. The client drives:

governance_catalog → stream_scorecard

Step 1 — find the stream

{
  "tool": "governance_catalog",
  "arguments": { "exchange": "coinbase", "datatype": "orderbook" }
}
[
  { "exchange": "coinbase", "market_type": "spot", "symbol": "BTC/USDT",
    "datatype": "orderbook", "presence": "present" }
]

Step 2 — score it

{
  "tool": "stream_scorecard",
  "arguments": {
    "exchange": "coinbase", "market_type": "spot",
    "symbol": "BTC/USDT", "datatype": "orderbook"
  }
}
{
  "stream": { "exchange": "coinbase", "market_type": "spot",
              "symbol": "BTC/USDT", "datatype": "orderbook" },
  "completeness": { "status": "critical", "completeness_pct": 0.049 },
  "quality": { "exception_count": 0, "max_severity": "none", "checks": [] }
}

Completeness is critical (completeness_pct is a 0–1 ratio, so 4.9%) while quality shows no exceptions — the stream is sparse, not corrupt. Add window_secs to recompute completeness live over a trailing window.


Compose the whole engagement

Ask — "Stand up a Binance BTC collector in a low-latency region, confirm it's landing data, audit an established stream, fit a Hawkes model to a trades dataset, forecast from it, then tear the collector down."

A capable client chains the flows above into one engagement, reading each result before the next and adapting as it goes:

flowchart LR
  H[platform_health] --> L[list_cex_options]
  L --> Q[query_colocation]
  Q --> D[deploy_collector]
  D --> CH[collector_health]
  CH --> G[stream_scorecard]
  G --> F[fit_hawkes]
  F --> FC[forecast_fit]
  FC --> S[stop_collector]
One engagement: check health, resolve the venue and region, deploy a remote collector, watch it land data, audit a stream's governance, fit a Hawkes model, forecast from the fit, and stop the collector.

Each arrow is a tool call whose result the client reads before the next, adapting as it goes — a looser tolerance on a non-converged fit, starting versus healthy on a fresh deploy.