# Official TheRundown Data MCP

> This is the official TheRundown source repository. `aigeon-ai/therundown` is unofficial.

The 0.4.0 source candidate registers 75 public REST operation tools, four bounded actual WebSocket capture tools, and six existing convenience tools. It uses the official MCP SDK and Node.js 22+. [COVERAGE.md](COVERAGE.md) lists exact routes, aliases, retired/private exclusions and transport limits.

The hosted account connection is `https://mcp.therundown.io/oauth/mcp`; legacy `/` and `/mcp` accept Product API keys in authenticated headers. The last live proof on 2026-10-03 found version 0.3.0 with six tools. This expanded candidate is not yet deployed or publicly listed. A personal connection is not a directory listing. The separate documentation MCP at `https://docs.therundown.io/mcp` cannot return Product prices.

ChatGPT uses Streamable HTTP. Each capture opens a real upstream WebSocket, observes at most five seconds / 50 messages / 256 KiB, then closes. It is not a continuous background feed. See [COVERAGE.md](COVERAGE.md) for channel, snapshot and resume limits, and [HOSTED.md](HOSTED.md) for deployment requirements.

Anonymous metadata and ping make no Product calls. Every data tool requires local key authentication or the connected account on the OAuth route. Keep credentials out of prompts, URLs, source, logs and browser bundles.

The historical source ZIP below remains 0.2.3 and does not include this candidate. There is no published npm package. That ZIP is stdio-only; `npm start` does not start the HTTP adapter.

Download the [versioned source bundle](https://therundown.io/downloads/therundown-data-mcp-0.2.3.zip), verify its [SHA-256 checksum](https://therundown.io/downloads/therundown-data-mcp-0.2.3.sha256), and extract it. The official ZIP is 41,072 bytes and its SHA-256 is `cb0a0841aa040f049ffddec5b5fa2436cb9de721a30a3bd53270132db7204025`. The [ZIP manifest](releases/0.2.3/MANIFEST.json) verifies every bundled source file. The ZIP README is generated from [BUNDLE-README.md](BUNDLE-README.md); this repository README also includes repository setup material. From the extracted ZIP directory:

```sh
npm ci --ignore-scripts
npm test
```

To run the checked-out source instead, use Node.js 22+ from this repository:

```sh
npm ci --ignore-scripts
npm test
```

For Claude Desktop's manual local configuration, add this to `claude_desktop_config.json` where supported and restart the client. Use absolute Node 22+ and server paths; this source ZIP is not a `.mcpb` desktop extension:

```json
{
  "mcpServers": {
    "therundown-data": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/therundown-data-mcp-0.2.3/server.mjs"],
      "env": { "THERUNDOWN_API_KEY": "YOUR_API_KEY" }
    }
  }
}
```

For Cursor, use the global `~/.cursor/mcp.json` and make the key available in the environment that launches Cursor:

```json
{
  "mcpServers": {
    "therundown-data": {
      "type": "stdio",
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/therundown-data-mcp-0.2.3/server.mjs"],
      "env": { "THERUNDOWN_API_KEY": "${env:THERUNDOWN_API_KEY}" }
    }
  }
}
```

Client references: [local MCP servers](https://modelcontextprotocol.io/docs/develop/connect-local-servers), [Cursor](https://cursor.com/docs/mcp).

Replace the path and key locally. Use your client's secret storage or inherited environment when available. Do not commit a filled-in client config. The server reads `THERUNDOWN_API_KEY` from its process environment and sends it only as `X-TheRundown-Key`; keys are never accepted as tool arguments. `stdout` contains only MCP protocol messages. Without a key, the process stays available for MCP metadata discovery and returns a sanitized `missing_credentials` error for Product tool calls without making a network request.

The original six convenience tools are:

| Tool | What it does | When not to use it for discovery |
| --- | --- | --- |
| `list_sports` | Lists current public sport IDs and names. | Do not infer that a sport has events or price coverage from its catalog row. |
| `list_affiliates` | Lists current public affiliate IDs and names. | Do not use it as proof that a book offers a requested sport or market; retired 27 is excluded. |
| `list_markets` | Lists market definitions, or date-scoped markets for a sport. | Do not treat definitions as open prices; date-scoped discovery rejects `live`. |
| `list_events` | Finds dated event summaries and available market IDs for one sport. | Do not select an event from memory or a similarly named result; resolve the exact participant, date, and timezone first. |
| `get_main_lines` | Fetches open per-affiliate main lines for one exact event ID. | Do not call it before `list_events`, or use it to search for an event; it requires the exact returned ID. |
| `list_futures` | Lists scoped futures competition boards with public schedule, settlement, and open main-line fields. | Do not use it for ordinary dated event discovery or assume a catalog/settlement status alone proves the board is fully settled. |

`list_markets` keeps catalog discovery and can also discover markets available for one `sport_id` and `date`; date-based discovery rejects `live` because that endpoint does not classify live markets. Event queries always use `main_line=true`, `hide_closed=true`, and `include=all_periods`. `list_futures` is an Ultra+ competition endpoint with scoped defaults `[1141]` and `[19,23]`, opaque cursor pagination, public schedule/settlement fields, and open per-affiliate main lines without line IDs. Defaults for dated event tools remain markets `[1,2,3]` and affiliates `[19,23]`. Pass live markets `[41,42,43]` explicitly. Retired affiliate 27 is rejected and excluded from discovery.

## First conversation

```text
Use TheRundown to list current sports and affiliates. Find MLB (sport 3).
For today's UTC date, list events with market_ids [1,2,3]
and affiliate_ids [19,23]. Select an event ID from that response and
call get_main_lines with the same filters.
Show the source URL, each book's line value and price updated_at,
and the returned usage headers. Explain empty results without inventing odds.
```

`npm test` runs offline. To check actual Product API data, privately set `THERUNDOWN_API_KEY` and run `npm run smoke`. The default checks pre-match `[1,2,3]` for MLB and affiliates `[19,23]`. Free includes delayed pre-match odds and excludes live odds, props/alternates, and history; a source catalog row does not grant access to it.

With an eligible key, `THERUNDOWN_SMOKE_LIVE=1 npm run smoke` also requests live `[41,42,43]`. `THERUNDOWN_SMOKE_DATE=YYYY-MM-DD` and `THERUNDOWN_SMOKE_SPORT_ID` select the dated scope. For a bounded Ultra+ competition check, set `THERUNDOWN_SMOKE_FUTURES=1` and a sport such as `40` (PGA) or `41` (Formula 1); it requests only market `1141` and affiliates `19,23`. The check has a 60-second deadline, verifies the reviewed source tool manifest, and reports its UTC check time, scope, selected event ID, source URLs, usage, and counts. Require `status: "ok"`, the full source tool manifest, and positive event/main-line counts. Empty data is inconclusive and exits 2. These requests are opt-in and metered.

Usage, API plan delays, and entitlements apply to every request. Catalog, date-market, event, and main-line pages paginate locally, so each page refetches a snapshot and is separately metered. `list_futures` uses the API's upstream opaque cursor and page limit; each cursor page is still a metered request and is only a partial competition listing when `has_more` is true. Results expose safe source URLs, retrieval timestamps, API usage headers, and per-price `updated_at`; a retrieval timestamp is not evidence that a price is fresh.

## Agent brief and errors (since 0.2.1)

Read `therundown://brief` through MCP resources for the current Build with AI
rules and first conversation. Initialization returns the same instructions;
neither operation calls the Product API.

HTTP failures return `status`, `plan`, `missing_entitlement`, `required_plan`,
`retry_after` (seconds), `remaining_points`, `monthly_remaining_points`, and
`limit_reason`, alongside the safe source URL, retrieval time, and usage headers.
Fields stay `null` when the API does not supply a recognized value. The server
does not guess the current plan from a denied feature. Raw upstream error bodies
are never returned, and errors do not trigger automatic retries.

An empty successful result retains its normal `data` shape and adds `empty`
with a code, explanation, and request scope. Dated results report the sport,
date, and date-boundary offset (UTC at zero); a page beyond existing results is
identified separately from an empty slate. Empty odds do not establish absent
coverage.

See [the setup guide](https://docs.therundown.io/data-mcp), [DESIGN.md](DESIGN.md), [authentication](https://docs.therundown.io/authentication), and [billing](https://docs.therundown.io/rate-limits). Read the [OpenAPI specification](https://docs.therundown.io/openapi.yaml), [sports catalog](https://therundown.io/api/v2/sports), [markets catalog](https://therundown.io/api/v2/markets), [affiliates catalog](https://therundown.io/api/v2/affiliates), [TheRundown llms.txt](https://therundown.io/llms.txt), and [documentation llms.txt](https://docs.therundown.io/llms.txt) for current public contracts and IDs.