odds-mcp

An MCP server over odds data where every read names its evidence and the one write is impossible without an approval token.

Model Context Protocol is how an LLM agent gets tools. The dangerous part is never the reads - it is the one tool that does something. This server demonstrates the pattern that makes side-effectful agent tools safe enough to exist: a risk envelope checked before a human ever sees the request, a single-use approval token issued by a separate step, a publish that cannot happen without it, and an append-only audit log that records every attempt - especially the refused ones.

Data comes from odds-consensus: 5 books normalized into one schema, de-margined fair prices, and a cross-book consensus view. This repo is the integration surface on top.

MCP client (Claude, any agent)
        │  tools
        ▼
  odds-mcp server ──── reads ────>  store.py   (consensus / fair price / outliers)
        │                              ▲
        └──── the one write ────> gate.py      propose → approve → publish
                                      │        (envelope · token · audit)
                                      └──────> out/audit_log.jsonl

Tools

Tool	Kind	Behavior
list_events	read	events in the snapshot
get_consensus	read	books per market, price ranges, median fair odds, outliers
get_fair_price	read	one market's fair price — or an explicit not-found with the valid alternatives. Ambiguous line? It asks. Single book? "A single book is not a consensus." Never a guess.
find_outliers	read	books off the consensus median, with exact deviation %
get_pipeline_health	read	counts plus every upstream devig refusal — what the snapshot does not cover
propose_boost	write-intent	checked against the risk envelope (max % over fair, stake cap) before a human sees it; refusals carry the reason
approve_proposal	human gate	issues a single-use approval token (production: a trader's Telegram approval card; same gate logic)
publish_boost	write	requires proposal id + matching token; token dies on use; replay fails
get_audit_trail	read	the append-only log of every attempt and outcome

Run it

pip install -r requirements.txt
python -m pytest tests/ -q          # 13 tests
PYTHONPATH=src python -m odds_mcp.server    # stdio MCP server

Claude Desktop config:

{"mcpServers": {"odds": {"command": "python", "args": ["-m", "odds_mcp.server"],
 "cwd": "<this repo>", "env": {"PYTHONPATH": "src"}}}}

What the tests pin down

• Publishing without approval: refused. Wrong token: refused. Replaying a used token: refused. (Tokens are single-use and compared constant-time.)
• A boost priced above the envelope (default: 5% over consensus fair) is refused at propose time, with the arithmetic in the reason.
• get_fair_price on a market with two live lines demands an explicit line instead of picking one; on a single-book market it refuses to call one price a "consensus".
• Every attempt - including every refusal - lands in the audit log.
• All 9 tools are actually registered on the server (test asserts the exact set).

Why this shape

An agent that can only read is safe but useless; an agent that can write is useful but dangerous. The resolution is not "trust the model" - it is structure: envelope, then human, then token, then audit. The model can draft; only the gate can act; and the log never forgets.

MIT licensed. Part of a set of small, honest data gates: jigonyoo.com.