Skip to main content
Status: local scaffold, September 6, 2026. Owner: TheRundown. The source bundle accompanies the local setup guide.

​
Scope

Make an agent’s first authenticated sports-data query explicit and reproducible. Five read-only tools cover reference discovery, event selection, and per-book main-line snapshots. They wrap existing Product V2 endpoints and inherit the calling key’s entitlements and billing. They do not access ingestion workers, internal databases, account mutations, or sportsbook wagering endpoints.
The official MCP SDK owns protocol negotiation, framing, cancellation, and tool schema validation. This scaffold registers tools with strict Zod input schemas. It has no HTTP listener, OAuth provider, remote session store, or published package identity. The documentation MCP remains a separate service.

​
Contract

Event tools require bounded canonical filters: 1–12 market IDs and 1–10 affiliate IDs. Defaults are [1,2,3] and [19,23]. Both force main_line=true&hide_closed=true&include=all_periods. No tool accepts a key, URL, host, path, or arbitrary query parameter. Date inputs must be real calendar dates; event IDs cannot contain path delimiters. Affiliate 27 remains off even if a stale upstream catalog returns it. Price projection preserves participant identity/type, market/period, line ID/value, affiliate ID, price, main-line state, and upstream update time. Main lines belong to each affiliate; different books can have different main values. Missing line values remain null (for example, moneyline). The scaffold does not calculate best price, implied probability, edge, or consensus, so it never mixes exchange/prediction-market quotes into sportsbook ranking. The result envelope is {source_url, retrieved_at, usage, data} in structured content and JSON text. Source URLs are reproducible and credential-free. Pagination provides items, total, page, limit, and next_page. Each page is a fresh upstream snapshot; local pagination is not a stable cursor or a billing optimization. Catalog presence and empty market responses are not evidence of full or absent coverage.

​
Request and credential boundaries

  • The executable uses one fixed HTTPS Product origin and GET-only paths. Redirects fail rather than forwarding a key to another origin.
  • The key comes from the process environment and is sent only in X-TheRundown-Key. The server does not read a repository .env automatically, log request headers, or return raw error bodies. Configured key text is redacted from tool output.
  • One request may be in flight. Extra concurrent calls return busy; calls are not queued and there are no automatic retries. Clients control request cadence and should respect 429/Retry-After and the calling plan’s quota.
  • A 15-second deadline and MCP cancellation abort the fetch/body read. Upstream bodies are capped at 4 MiB before JSON parsing. Large requests fail explicitly instead of returning silent partial odds.
  • Only allowlisted usage/entitlement headers are returned. 401, 403, 404, and 429 get useful, sanitized messages. Transport and unexpected errors get a generic error; stdout is reserved for MCP.
An API key can incur data-point usage even for read-only tools. A page limit trims agent output only. The client should present tool calls and costs to its user according to its normal permissions model.

​
Verification

Offline tests exercise MCP initialization/discovery, strict schemas, header-only requests, raw-array market definitions, event envelopes, per-book line preservation, retirement filtering, usage headers, errors, cancellation/timeouts, and bounded response handling. The stdio smoke client checks the actual executable; network calls happen only when explicitly running npm run smoke with a key. The smoke client defaults to pre-match markets 1/2/3 for sport 3 and affiliates 19/23. An eligible key can opt into the combined pre-match/live check with THERUNDOWN_SMOKE_LIVE=1, adding 41/42/43. It validates the exact five-tool contract before data requests, selects an event whose summary reports a requested market ID, spaces its two Product API calls by one second for Free-plan compatibility, and reports the UTC check time, requested scope, selected event ID, source URLs, counts, and usage. Smoke acceptance uses an active date with both main-line/open filters. Require a selected event ID and positive visible prices. Record this output without keys or full customer payloads. An empty date is inconclusive. A successful narrow check says nothing about other sports, sources, freshness guarantees, or WebSocket delivery.

​
Publication sequence

  1. Merge the tested source and guide, verify published links, and run the exact live smoke request. Keep the package private until an artifact release is deliberately prepared.
  2. Choose distribution: a versioned package or MCPB for local clients, or an operated Streamable HTTP service. Provide reproducible installation, a license decision, ownership metadata, and a support/update policy.
  3. A hosted service needs MCP authentication, per-user upstream-key isolation, request/rate budgets, secret redaction, Origin validation, session isolation and bounded shutdown. Implement the MCP authorization specification; do not treat a caller’s MCP access token as a Product API key or blindly pass it to the upstream API. No hosted URL is advertised by this scaffold.
  4. Publish a real artifact and valid server.json using a verified namespace, then submit registry metadata. Do not create metadata pointing to a nonexistent npm package or remote URL. Confirm directory-specific prerequisites before submitting.
  5. Verify the registry entry, install from the public artifact, and record a working listing URL before changing outreach copy to claim availability. Outreach drafts are prepared under operations/ai-discovery; sending remains a separate action.
References: official SDK server guide, MCP tool specification, MCP authorization, registry quickstart, TheRundown OpenAPI.