mcp-financial-data

An MCP server (spec 2025-11-25) for SEC EDGAR + FRED + Polygon.io with OAuth 2.1, a citation-grounded 10-K extractor powered by Claude Sonnet 4.5, and an MCP Apps inline UI for the extracted summary.

Anchor audience: Anthropic Forward Deployed Engineering, Bridgewater / Citadel / Anthropic Finance teams.

This repo is project P1 of a running May 18 – June 21, 2026.

Why this exists

Financial-services AI work consistently fails the same audit checklist:

1. The agent answered with a number, but the citation pointed at the wrong filing.

2. The agent dropped a fact silently when the source didn't support it.

3. The MCP integration didn't validate JWT scopes per request.

4. The eval harness wasn't deterministic, so the regression yesterday is indistinguishable from a flaky judge today.

Every one of these is a hard constraint in this repo, enforced in CI.

Architecture

flowchart LR
    Client["MCP Client (Claude Desktop / Cursor / Goose)"] -->|"OAuth 2.1 + PKCE"| Server[FastMCP Server]
    Server --> EDGAR[EDGAR async client]
    Server --> FRED[FRED async client]
    Server --> Polygon[Polygon.io async client]
    Server --> Extractor["10-K Extractor (Claude Sonnet 4.5 + Citations)"]
    Server --> Apps["MCP Apps inline UI"]
    EDGAR --> Cache[(Postgres response cache 24h TTL)]
    FRED --> Cache
    Polygon --> Cache
    Extractor --> Cache
    Server --> Evals["evals/harness.py (JSONL runs)"]

Quickstart

git clone https://github.com/SebAustin/mcp-financial-data.git
cd mcp-financial-data
cp .env.example .env   # fill in API keys
make setup             # uv sync + pre-commit install
make ci                # lint + typecheck + tests + smoke eval (offline)
make serve             # run the MCP server on $MCP_HOST:$MCP_PORT

The full Cursor build order lives in prompts/00_kickoff.md.

What's in the box

Eval targets (W1)

The eval harness writes per-case JSONL plus a summary JSON to evals/runs/<run_id>/. CI runs --smoke --offline on every PR; nightly CI runs --full against live APIs with a $5 spend cap.

Hard constraints (skim before contributing)

• Citations are non-optional for the 10-K extractor. Every CitedClaim.text carries at least one Citation. Uncited model output is dropped or moved to notes with [INFERENCE]. See docs/adr/0003-citations-required-for-extracted-claims.md.

• EDGAR Fair Access is enforced. Every request carries the EDGAR_USER_AGENT env value. Process rate limit ≤ 10 req/sec.

• Spend cap. MAX_API_SPEND_USD defaults to 50. Enforced in extractor and harness.

• No requests, no print(), no subprocess shell=True, no bare except.

• OAuth 2.1 RS only. This server validates JWTs; it is never the IdP. See docs/adr/0004-oauth21-as-resource-server.md.

Layout

src/mcp_financial_data/      # the package
  server.py                  # FastMCP entrypoint
  auth/oauth.py              # OAuth 2.1 RS primitives
  tools/{edgar,fred,polygon} # async API clients
  extractors/tenk.py         # citation-grounded 10-K extractor
  apps/ui.py                 # MCP Apps inline UI registration
  evals/{harness,metrics}    # eval harness (--smoke / --full / --offline)
tests/{unit,integration}     # pytest, 85% gate, integration skipped by default
evals/cases/seed.jsonl       # 5 hand-authored eval cases
evals/runs/                  # per-SHA harness output (gitignored)
prompts/                     # Cursor prompt pack: kickoff + 6 follow-ups + Loom
docs/adr/                    # MADR architecture decisions
.github/                     # CI templates + issue/PR templates + dependabot

References

License

MIT. See LICENSE.