Skip to content

API and MCP

Savvas Leousis edited this page Sep 26, 2026 · 2 revisions

API and MCP

stonks serve runs a REST API over the same services the CLI uses. stonks mcp lets Claude talk to that API.

flowchart LR
  WEB[Web console] --> API
  CL[Claude Code / Desktop] -->|stdio| MCP[stonks mcp]
  MCP -->|HTTP + token| API[stonks serve<br/>127.0.0.1:8000]
  API --> SVC[app services]
  SVC --> DB[(lake + state)]
Loading

Start the API

export STONKS_API_TOKEN=pick-a-long-random-string
uv run stonks serve                    # http://127.0.0.1:8000
uv run stonks serve --host 0.0.0.0 --port 9000 --reload

It also serves the built web console from web/dist when present.

Auth in plain words

  • The token comes only from the STONKS_API_TOKEN env var, never from a config file.
  • Reading (GET) from the same machine needs no token (open_reads_on_loopback = true).
  • Anything that changes something needs Authorization: Bearer <token>.
  • No token configured means every write is refused.
  • It binds to 127.0.0.1 by default, and only accepts known Host headers (allowed_hosts).

Route groups

Prefix For
/api/health Liveness probe and health report
/api/auth Token check
/api/alerts Alerts feed
/api/portfolio, /api/pnl Current portfolio, snapshots, P&L
/api/strategies List, detail, promote, shadow, retire, go-live checks, P&L
/api/shadow Shadow decisions and virtual P&L
/api/market Instruments, bars, data coverage
/api/ingest Ingest runs; start an ingest
/api/lab Start backtests and lab runs, results, cost models
/api/ticks Tick history; start a tick
/api/orders Orders and fills
/api/studio Strategy Studio drafts
/api/catalog Strategies with parameter specs, intervals, asset classes
/api/risk, /api/brokers, /api/sources Risk policy, broker info, data sources
/api/jobs Background jobs

The OpenAPI contract is in web/openapi.json. Every route is listed on API Reference and in the Swagger UI.

Not yet in the API: users and login, subscriptions, broker connections, push subscriptions and metrics. Those are CLI or service only for now (see Accounts and Modes).

Background jobs and live progress

Long work (backtest, lab run, ingest, tick) returns a job right away.

  1. POST /api/lab/runs returns a job id.
  2. Poll GET /api/jobs/{id}, or stream progress with server-sent events at /api/jobs/{id}/events.
  3. Browsers cannot send the bearer header to an event stream, so first call POST /api/jobs/{id}/stream-token for a short-lived URL.
  4. Cancel with POST /api/jobs/{id}/cancel.

Up to max_concurrent_jobs (2) backtests and lab runs run at once. Ticks and ingests each have their own worker.

MCP server

MCP (Model Context Protocol) lets an AI assistant call tools. stonks mcp never opens the databases; it calls the running API. Start stonks serve first.

Register with Claude Code, from the repo root:

claude mcp add stonks --env STONKS_API_TOKEN=your-token -- uv run --directory "$(pwd)" stonks mcp

Claude Desktop (claude_desktop_config.json):

{"mcpServers": {"stonks": {
  "command": "uv",
  "args": ["run", "--directory", "C:\\path\\to\\Stonks", "stonks", "mcp"],
  "env": {"STONKS_API_TOKEN": "your-token"}}}}
Kind Tools
Read portfolio, P&L, strategies, reports, bars, orders, ticks, catalog, jobs, health, ...
Jobs backtests, lab runs, ingest
Guarded writes promote, shadow, retire, tick, Studio drafts

The full, generated list is on MCP Tools.

MCP safety

  • Guarded writes without confirm: true only return a preview.
  • run_tick is a dry run unless you pass dry_run: false, and a real tick is refused unless the API reports a simulated or paper broker.
  • No tool changes config or enables live trading.
  • The token is never sent over plain http to a non-local host.

More: docs/mcp.md in the repo.

Clone this wiki locally