therundown://brief read do not call the Product API. Product tool calls still require your key, and your plan’s data delay, coverage, entitlements, and data-point billing still apply.
Official sources: the hosted endpoint at
https://mcp.therundown.io/mcp
and TheRundown/data-mcp (source and
versioned bundle, for the local stdio install below) are both official. The
aigeon-ai/therundown repository is unofficial, and there is still no
published npm package. The existing documentation MCP
at https://docs.therundown.io/mcp searches documentation only.Hosted endpoint
The same six tools are also available over a hosted, authenticated Streamable HTTP endpoint. No local install or Node.js runtime is required:POST; a plain GET correctly returns 405. A request carrying any Origin other than the endpoint’s own is rejected with 403, so do not call it from a web page, which would also expose your key. Send your Product API key in exactly one header, never both. Use the recommended X-TheRundown-Key header, which matches Authentication:
THERUNDOWN_API_KEY in the environment that launches the client, so the key never appears in the config file or in command-line arguments. Claude Code expands ${THERUNDOWN_API_KEY} in a project .mcp.json when it connects; Cursor’s equivalent is ${env:THERUNDOWN_API_KEY}; Codex maps the request header to the variable with env_http_headers. Populate the variable from a secret manager or a silent prompt such as read -rs THERUNDOWN_API_KEY && export THERUNDOWN_API_KEY, not by typing the key into a command your shell records in its history. VS Code can instead prompt for the key and store it securely as an input value.
.vscode/mcp.json. See VS Code’s MCP configuration reference and OpenAI’s Codex MCP documentation for the client-specific fields above.
Per key, one request may be in flight; the process also caps overall concurrent requests and returns 429 with Retry-After: 1 when full. Request bodies are capped at 64 KiB, and the request deadline defaults to 20 seconds. Sanitized errors carry structured error.data — status, plan, missing_entitlement, required_plan, retry_after, remaining_points, monthly_remaining_points, and limit_reason — so a client can react programmatically. Keep real keys out of prompts, source files, URLs, and logs, the same as the REST API’s X-TheRundown-Key header.
Metadata discovery is intentionally separate from Product data access. With the local 0.2.3 stdio server, initialize, the initialized notification, tools/list, resources/list, and resources/read for exactly therundown://brief work without a key and do not validate a key or entitlement. A local Product tool call without a key returns a sanitized missing_credentials error before any upstream request. For the hosted endpoint, configure the documented key header before connecting. An otherwise-valid unauthenticated MCP POST/JSON-RPC request for a Product tool returns HTTP 401 with structured error.data; a plain GET remains the separate transport probe with HTTP 405, and transport or Origin guard failures have their own transport status.
Choose the hosted endpoint for zero local install, or the local stdio install below when you want a process that runs on your machine and does not call the hosted MCP endpoint. The local server still makes HTTPS calls to the Product API with your key.
Install from source
This is the local-install path: a stdio server that runs on your machine and does not call the hosted MCP endpoint. It still makes HTTPS Product API calls with your key, so it is not suitable for a fully offline or network-isolated environment. Download the versioned source bundle, extract it locally, and install the locked dependencies. The official public source repository is the canonical source; GitHub access is not required when using the bundle. The archive includes the server, dependency lockfile, design, and offline tests:sha256sum -c therundown-data-mcp-0.2.3.sha256 (Linux) or shasum -a 256 -c therundown-data-mcp-0.2.3.sha256 (macOS). The expected archive SHA-256 is cb0a0841aa040f049ffddec5b5fa2436cb9de721a30a3bd53270132db7204025. The archive also contains MANIFEST.json with its version and individual file hashes.
Connect an MCP client
These configurations connect a client to the local stdio install above; see Hosted endpoint for the zero-install alternative. Replace both paths below with the absolute Node.js 22+ executable and extractedserver.mjs. An absolute Node path also works when a desktop app does not inherit your terminal’s Node version. Keep real keys in private local configuration or the client’s supported secret/environment mechanism.
Claude Desktop
Use this entry inclaude_desktop_config.json, then restart Claude Desktop. This source ZIP is not a .mcpb desktop extension. See the official local-server configuration guide.
Cursor
Add this entry to the global~/.cursor/mcp.json. Make THERUNDOWN_API_KEY available in the environment that launches Cursor, then reload its MCP servers. The environment reference keeps the key value out of the JSON. See Cursor’s MCP instructions.
Codex
Set or exportTHERUNDOWN_API_KEY privately in the environment that launches Codex. Add this entry to ~/.codex/config.toml, replacing the two absolute paths with the Node.js 22+ executable and extracted server.mjs paths from the setup above:
env_vars forwards the named environment variable to the MCP server without copying its value into TOML. See OpenAI’s Codex MCP documentation for client configuration details.
Start a new Codex session from that environment and confirm that it exposes the six tools. Follow First conversation, then Verify a real request to check API access.
The server reads THERUNDOWN_API_KEY from its environment and sends it to the Product API in X-TheRundown-Key. Tool arguments never accept credentials, arbitrary URLs, or custom headers. Without a key, metadata discovery and the exact therundown://brief read remain available, while Product tool calls return missing_credentials without making a network request. Never commit a client configuration containing a real key.
Brief, scope, and outcomes
Read thetherundown://brief resource before asking for data; the hosted
endpoint and the local server both expose it. It starts
with four rules: resolve the event first; every price carries event, market,
affiliate, line, and updated_at evidence; missing stays missing; and IDs come
from the API at runtime, with retired identities excluded.
Requests are scoped to the selected public IDs and filters. An empty result
means no data for that scope, not that an event, source, or market is universally
unavailable. Preserve a returned null line value as null. Treat a sanitized
401, 403, or 429 response separately from an empty result, and use the
documented header-based Product API key boundary rather than a query key.
Tools and output schemas
Each tool has a human-readable title and advertises an object-root structured output schema. Successful results use the common envelope{source_url, retrieved_at, usage, data}; empty results add empty, and
sanitized failures add the documented error fields. The six titled data
schemas are:
Fields shown as nullable or optional by the server remain absent or
null as
returned. The schemas describe the curated public projection, not the full
Product API response.
Tools
The dated event tools default to
market_ids: [1, 2, 3] and affiliate_ids: [19, 23]. They always request main_line=true&hide_closed=true&include=all_periods. list_futures defaults to market_ids: [1141] and the same affiliates; its response keeps only open per-affiliate main lines and public competition schedule/settlement fields. Pass live IDs 41,42,43 explicitly for in-play moneyline, spread, and total. Discover other markets instead of guessing IDs.
Both transports accept at most 12 market IDs and 10 affiliate IDs per call. Pages contain at most 200 items; the default is 50. Catalog, date-market, event, and main-line pagination happens inside the MCP server: another page fetches another full filtered API response, incurs its normal usage, and may reflect a newer snapshot. list_futures instead forwards the API’s opaque cursor and page limit; each cursor page is still metered, and has_more means the response is only a partial competition listing. Reduce market/book filters to reduce billing; lowering a local page size only reduces tool output.
First conversation
source_url, retrieved_at, usage, and data. retrieved_at is the HTTP retrieval time, not the freshness of an individual price. Use the price’s updated_at and your key’s delay entitlement. A sport or affiliate catalog entry does not guarantee an open offer for a particular event.
Verify a real request
This check is for the local install. On the hosted endpoint, run First conversation from your connected client instead; a non-emptyget_main_lines result confirms your key and entitlement end to end.
After setting THERUNDOWN_API_KEY privately in your environment, run:
npm test is offline. By default, the smoke check uses sport ID 3, affiliate IDs 19/23, and pre-match markets 1,2,3, so it does not request live access on a Free key. Free covers delayed pre-match odds within its published allowance; it excludes live odds, props/alternates, and history. Check current entitlements for your key.
With an eligible key, explicitly include live markets 41,42,43:
status: "ok", tools: 6, and positive events and main_lines counts. The script verifies the exact six tool names before making data requests. Set THERUNDOWN_SMOKE_SPORT_ID and THERUNDOWN_SMOKE_DATE=YYYY-MM-DD for a dated scope. With an eligible Ultra+ key, set THERUNDOWN_SMOKE_FUTURES=1 for one bounded future page using market 1141, affiliates 19,23, and the selected sport; lower tiers may return a documented 403 entitlement result. The script has a 60-second deadline. A positive response is a snapshot check, not a latency or all-source coverage benchmark.
Limits and next steps
Both transports allow one in-flight API call (per process locally, per key on the hosted endpoint), use a 15-second upstream timeout and a 4 MiB upstream response limit, reject redirects, and never retry automatically. The hosted endpoint adds its own 64 KiB request-body cap, 20-second request deadline, and overall concurrency cap; see Hosted endpoint. On429, follow the returned retry_after and usage headers. API errors are sanitized before reaching the assistant.
Both transports provide REST snapshots. Streaming, bet placement, account changes, OAuth, and package publication are out of scope. Read the design and release criteria before operating a shared service.
For a pasteable API integration brief, see Build with AI. For the underlying contracts, use the OpenAPI specification, authentication guide, and market reference.