Trading Desk

Multi-agent equity research for US markets, running on Claude Code subagents over MCP. Analysis-first: real money is never touched, and order flow goes to an Alpaca paper account.

Why this exists

Financial data is easy to fetch and easy to get wrong. US-GAAP XBRL concepts drift per company and over time, so reading a single hardcoded concept returns figures that are years stale with no error raised:

An agent given $62.9B for Apple writes a confident, completely wrong thesis. The whole design follows from preventing that.

Operating rules

1. Agents never compute and never recall. Every number comes from a tool call; ratios and indicators are calculated in Python.

2. Every value carries provenance — XBRL concept, period, form, accession, filing date — so any figure can be traced back to the filing.

3. Stale data raises. A number too old to answer the question is an error, not a footnote.

4. Concept resolution is code with tests, not a prompt instruction.

Related MCP server: ReadyTrader-Stocks

Status

Complete. Research, sizing, a scoreable record, the context around a name, paper execution that cannot be reached except through an approved thesis, and a loop that grades the calls afterwards.

• EDGAR client — rate limited, disk cached, no API key required

• Concept resolver with provenance and staleness enforcement

• Golden tests (23) pinned to filed 10-Ks

• desk MCP server, verified over stdio

• Phase 1 — fundamentals + chartist agents, /analyze

• Phase 2 — risk (veto) + journal, /journal

• Phase 3 — filings, macro, screener

• Phase 4 — pilot, Alpaca paper execution behind risk approval

• Phase 5 — /postmortem calibration loop

• Phase 6 — capitol, oracle, ledger

• Phase 7 — /nimbus orchestrator

The agents

Ten specialists, each with a narrow remit and a matching tool allowlist. None of them computes anything; every figure comes from a tool call.

Orchestration

/nimbus is the front door. It takes any request — a ticker, a question, a half-formed worry — routes it to the specialists that can answer it, and reconciles what comes back into one view.

It runs in the main thread rather than as a subagent, deliberately: an agent dispatching agents nests badly, and parallel dispatch is only available where the conversation is. Independent specialists go out in a single message and come back concurrently; their independence is what makes agreement between them worth anything.

Nimbus holds no view of its own. Every claim in its output came back from a specialist in that session, and a figure it cannot attribute to a tool call is one it must not state. It also defers rather than rebuilds — a full research pass on a ticker is handed to /analyze, not reimplemented.

Money moves through exactly one sequence, and the orchestrator never shortens it:

research → risk approves → thesis journalled → place_order(thesis_id)

A request to "just buy 100 shares" has no way to be expressed — place_order takes a thesis id and nothing else.

The dashboard

A local Streamlit app over the same desk_mcp modules the agents call:

uv run --extra ui streamlit run desk_ui/Home.py

No language model runs in it. Everything it shows — financials, metrics, technicals, sizing, forecasts, 13F and congressional disclosures, the journal, the scoreboard, desk health — is deterministic Python. Judgement stays in Claude Code, where the agents live; the dashboard is for the parts that were never judgement to begin with.

The app inherits the desk's rules rather than restating them. Figures carry the period and the concept they came from. A failed call renders as a named gap, because an empty table reads as an answer. limitations are rendered inline and never behind a collapsed panel — a limitation nobody reads is one that does not exist.

Two journal rules are enforced in the form, since this is the one place a call can be written without an agent having read them first: a thesis will not record without a falsifier, and a position will not close without an exit price. Both are tested.

Exposing it

It binds to 127.0.0.1 via .streamlit/config.toml. Streamlit's own default is 0.0.0.0, which publishes an external URL — unsuitable here, because the app writes to the journal and Streamlit ships no authentication. Anyone reaching the URL would be the operator.

Hosting it later means a reverse proxy with real authentication in front, and DESK_UI_READONLY=1 unless writes are genuinely needed:

DESK_UI_READONLY=1 uv run --extra ui streamlit run desk_ui/Home.py

Changing the bind address alone is not enough.

Setup

uv sync
uv run pytest tests/golden -q     # must be green before any agent work

Credentials

Keys live in the environment, never in the repo — .mcp.json reads them via ${VAR} expansion. Put them in ~/.zshrc so they cannot be committed by accident.

Paper trading needs no funding, identity check or approval — that applies only to live accounts.

Verify without exposing anything (the script prints presence and a masked prefix only, never a secret):

uv run python scripts/check_keys.py

Data sources

Deliberately not used: yfinance (unofficial endpoints, silent empty responses) and Stooq (now behind a JS proof-of-work wall). EDGAR is preferred for fundamentals because it is the source of record rather than a scrape of it.

MCP tools

Risk limits

The risk agent holds a veto and does not exercise judgement about it — the limits are policy, checked in Python, and quoted back with the reason they exist. get_risk_policy returns them at runtime.

Correlation is the one call the checks cannot make: three 1% positions on the same driver are one 3% position in disguise, and the agent is instructed to veto that even when every numeric limit passes.

The journal

Theses are JSON files under theses/, one per call, written at the moment the call is made — greppable, diffable, and reviewable alongside the code that produced them. A thesis will not record without at least one falsifier, and direction="watch" calls are recorded too: a watchlist name that ran away without you is as informative as a trade that failed, and only one of the two tends to get remembered. Realised R is computed on close from the recorded entry and stop, so outcomes compare across positions of different sizes.

Set DESK_THESES_DIR to keep the book somewhere other than the repository.

Smart money

Three populations, three different signals, and conflating them is how this data gets misread. All of it is disclosed late; the discipline is refusing to describe stale filings in the present tense.

13Fs are aggregated per security. A manager with sub-advisers files the same issuer on many lines — Berkshire reports Apple twelve times — so reading the table row-wise reports a twelfth of the real position. Changes are computed from share counts, never values: a holding marked down by the market is not a sale, and treating it as one is simply wrong. Each position carries implied_price_per_share as a self-check, because filings before 2023 reported value in thousands rather than dollars.

Congressional amounts are statutory bands. $1,001 - $15,000 is what was filed; a midpoint is a number nobody reported. Transactions live inside filing PDFs, so they are parsed from extracted text and every row carries the document link. Scanned filings that extract to nothing are reported under unreadable_filings rather than dropped — a member whose filing cannot be read is not a member who did not trade.

Forecasting

oracle produces distributions, never predictions, and the reason is worth stating plainly.

Drift is assumed to be zero. Not because stocks do not rise, but because drift cannot be estimated from the data available: the standard error of a mean return measured from a year of daily data is roughly the annual volatility itself, so a measured 12% drift on a 30%-vol name carries an error bar of about ±30%. Volatility is estimable from the same sample to within a few percent. So the model forecasts the spread and refuses to forecast direction — which makes it useless for picking sides and useful for the questions intuition gets wrong.

Two models run on every question. Gaussian is analytically clean and wrong in the tails; bootstrap resamples the name's own history and carries its real skew. Where they disagree, the normal assumption is doing damage, and the gap is reported rather than averaged away.

The most decision-useful output is edge_vs_breakeven. A 2:1 setup must reach target a third of the time simply to break even. When the modelled probability sits below that, the geometry does not pay under zero drift and the entire case has to come from the thesis — which the model cannot see and will not pretend to.

analytic_unlimited_time is the closed form for a driftless walk, where the odds depend only on the log distances to each barrier. Simulated figures sit below it because the horizon expires; a large gap means the trade is not wrong, it is being given too little time.

Barriers are checked at daily closes, so an intraday spike through the stop that closes back inside is not counted — real stop-outs are somewhat more likely than reported. Results are seeded, so the same question returns the same answer; a probability that moved on refresh could not be quoted in a thesis or checked afterwards.

Desk health

get_desk_health audits the desk rather than a company, because the failures that corrupt every other number here are silent ones:

It runs offline and checks credentials for presence, not validity — a revoked key passes here and fails at the call site. Values are never read into a response.

The calibration loop

/postmortem grades what the journal recorded. It asks two questions that are routinely confused for one:

Was the call right? Expectancy in R, win rate, payoff ratio — all computed in Python, all quoted rather than derived by an agent.

Was it right for the reason given? Every thesis stores falsifiers, and review_thesis returns them unchecked. Answering them means dispatching the chartist at the price level, or the filings agent at the disclosure, and finding out what actually happened. A thesis that worked because of something nobody in the evidence predicted is a losing process with a winning outcome, and it is the result most likely to be repeated.

Three numbers do the calibration work:

Nothing that produced no R is quietly counted as a scratch. Watch calls have no R by design; a position closed without an exit price is a record-keeping failure. Both appear under unscored with the reason, and both are excluded from every performance figure rather than dragging it toward zero.

minimum_meaningful_sample is 20. Below it the skill is instructed to report the numbers as descriptive and draw no inference — three losing trades is not evidence of a broken process, and changing the rules on that basis is worse than doing nothing.

Findings propose changes; they do not make them. A limit that should move is a change to desk_mcp/risk.py, argued for separately — a rule rewritten in the same pass that discovered it has never been argued with.

Execution

Paper only. The base URL is the paper endpoint, hardcoded with no environment variable that redirects it, and the account number is checked for Alpaca's PA prefix before any order is sent — live keys against the paper URL fail closed rather than trading.

The gate is the shape of the function rather than an instruction to an agent:

place_order(thesis_id)      # and nothing else

There is no symbol parameter, no quantity, no price. All of it is read back out of the journal entry, which exists only because the risk officer approved it and only carries a share count the risk officer computed. An agent asked to buy 100 shares of something has no way to express that.

An order is refused when the thesis is closed, is a watch call, carries a vetoed verdict, was sized at zero shares, lacks an entry or stop, or already has an order attached — the last of which is what stops a retried call from opening a second position in the same name.

Orders go out as brackets, so the stop the risk officer sized against is submitted with the entry rather than left to a later call that might never happen. reconcile_positions compares what the broker holds against what the journal knows about, which is the only way to see the untracked exposure that portfolio heat is blind to.

Known limitations

• Q4 quarterly gaps. Q4 gets no standalone 10-Q; it must be derived as FY minus Q1–Q3. Not yet implemented — quarterly series skip Q4.

• Alpaca free tier is IEX-only (~2% of consolidated volume), so daily-bar volume is unreliable for swing setups. The price layer sits behind an adapter so Tiingo or another EOD source can be swapped in without touching agent code. Same seam later carries a non-US broker.

• Non-US-GAAP filers (foreign issuers on IFRS) are not covered by the current concept registry.

• The screener has no universe. It ranks a list you give it and reads the venue's movers and most-active tables. It cannot screen "all US software above $2B" — there is no fundamental universe behind it, and a themed list assembled by an agent is a recollection, not a screen. The screener agent is instructed to say which it is.

• Filing text is text. get_filing_text strips markup and returns what was filed. Tables survive as readable rows, but nothing is parsed into figures — a number read out of filing prose has no XBRL concept behind it, so prefer get_financials whenever the figure exists there.

• Macro needs its own key. Without FRED_API_KEY the macro tools fail with a message saying where to get one. Nothing else on the desk depends on them.

• A submitted order is not a filled one. A limit entry may never fill, and the position does not exist until it does. The pilot agent is instructed never to describe one as the other.

• Portfolio heat only sees the journal. A position taken without recording it is invisible to the risk checks, so the heat number is exposure as recorded rather than exposure as held. size_position says so in its limitations on every call.

• 13Fs are long US equity only. No shorts, no cash, no bonds, no foreign listings. Portfolio weights are weights within the reported slice, so a manager described as "22% in Apple" is 22% of the part they had to disclose.

• Congress coverage is House-only and partial. The Senate publishes separately and is not read. Only the reports actually opened are searched, so an absent ticker means "not in the reports read", never "not traded" — the response states how many of how many were parsed.

• Congressional trades are parsed from PDF text, with no structured source behind them. The same caveat as filing text, one step weaker: follow the document link before quoting a specific transaction.

• Forecasts assume volatility persists and drift is zero. Neither holds across an earnings date, and the bands are wrong in both directions over one. The bootstrap resamples days independently, so it reproduces fat tails but not volatility clustering — real drawdowns arrive in consecutive sessions more often than the model allows.

• get_desk_health is offline. A reachable-but-broken API looks healthy, and a revoked credential passes a presence check.

Not financial advice

A research tool, not a prediction engine. /postmortem exists because calls need to be scored honestly rather than remembered selectively — and a good scoreboard is not a reason to trade larger. The limits do not move because recent results were pleasant.