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

Related MCP server: polyrouter-mcp

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.