whensport API & MCP

Two surfaces, same data

MCP server

One endpoint, 10 sports, 48 tools, all on the official MCP Registry. Connect any MCP-compatible client to https://whensport.com/mcp and your AI assistant can answer "when does Brazil play in my timezone?", "what's the next polo final?", or "what stage of the Tour de France is this?" with canonical data.

Connect from Claude

# In Claude Desktop config (or .mcp.json):
{
  "mcpServers": {
    "whensport": {
      "url": "https://whensport.com/mcp",
      "transport": "streamable-http"
    }
  }
}

Connect from Cursor / Continue / Cline

All MCP-compatible IDEs use the same shape. Add the URL https://whensport.com/mcp as a streamable-http MCP server in your IDE's MCP settings.

Sport-specific endpoints

Want only one sport's tools? Each sport has its own filtered MCP endpoint with a smaller catalog — better for context-conscious agents.

Tool namespaces

Every tool is namespaced under whensport_. The canonical form is e.g. whensport_f1_getNextRace.

• FIFA World Cup — whensport_getCountrySchedule, whensport_getTeamMatches, whensport_getMatch, whensport_findToday, whensport_getCurrentlyLive, whensport_getCountryList
• F1 — whensport_f1_getRaces, whensport_f1_getRace, whensport_f1_getNextRace, whensport_f1_getDrivers, whensport_f1_getTeams
• Tennis — whensport_tennis_getTournaments, whensport_tennis_getTournament, whensport_tennis_getNextGrandSlam, whensport_tennis_getVenues, whensport_tennis_getPlayers
• Cricket — whensport_cricket_getTournaments, whensport_cricket_getTournament, whensport_cricket_getMatches, whensport_cricket_getMatch, whensport_cricket_getPlayers, whensport_cricket_getTeams
• Rugby — whensport_rugby_getTournaments, whensport_rugby_getTournament, whensport_rugby_getMatches, whensport_rugby_getMatch, whensport_rugby_getTeams
• Golf Majors — whensport_golf_getTournaments, whensport_golf_getTournament, whensport_golf_getNextMajor, whensport_golf_getVenues, whensport_golf_getPlayers
• Polo — whensport_polo_getTournaments, whensport_polo_getTournament, whensport_polo_getVenues, whensport_polo_getTeams, whensport_polo_getPlayers
• Sailing — whensport_sailing_getEvents, whensport_sailing_getEvent, whensport_sailing_getVenues, whensport_sailing_getTeams
• Horse Racing — whensport_hr_getMeetings, whensport_hr_getMeeting, whensport_hr_getVenues
• Tour de France — whensport_tdf_getStages, whensport_tdf_getStage, whensport_tdf_getStagesInRange, whensport_tdf_getRacePhase

All tools are read-only (D1 SELECTs only). No writes, no side effects — clients can call freely without user-confirmation prompts.

Editorial field

Every entity returned by the MCP carries an editorial object surfacing the canonical lead, URL, and last-updated date — the same content powering the public whensport.com pages, exposed structurally so AI agents can quote it.

{
  "editorial": {
    "lead": "30-200 char hook, first paragraph from the editorial markdown",
    "url": "https://whensport.com/events/...",
    "lastUpdated": "2026-04-15"
  } | null,
  "crossReferences": []
}

editorial is null when no markdown content exists for the entity. crossReferences ships as an empty array; future canonical-domain MCPs (timezone.tax, etc.) will populate it with cross-domain teasers and MCP-server hints.

Test the MCP from a terminal

# List available tools (broad endpoint, all 48)
curl -X POST https://whensport.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq

# Call a tool — every tool is namespaced under whensport_
curl -X POST https://whensport.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"whensport_getCountrySchedule",
                 "arguments":{"country":"japan","limit":3}}}' | jq

# Or use a sport-filtered endpoint (only 5 polo tools listed)
curl -X POST https://whensport.com/mcp/polo \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/list"}' | jq

REST API

Same data as the MCP, exposed as classic GET endpoints with JSON responses. No auth required. CORS open. Edge-cached 30–300 seconds depending on volatility.

Sport namespaces

One catch-all path per sport. Each one is the REST mirror of the matching MCP namespace.

Each base path returns its endpoint manifest when called directly (e.g. GET /api/v1/polo/ lists its routes).

WC 2026 endpoints (most-used set)

Try it

# WC 2026 country schedule (Japan, default JST)
curl https://whensport.com/api/v1/wc-2026/countries/japan/schedule | jq

# F1 next race
curl https://whensport.com/api/v1/f1-2026/next | jq

# Polo tournaments
curl https://whensport.com/api/v1/polo/tournaments | jq

# Tour de France stages 1-3
curl https://whensport.com/api/v1/tour-de-france-2026/stages/1 | jq

# What's the next golf Major?
curl https://whensport.com/api/v1/golf-majors-2026/next-major | jq

Rate limits

Rate-limited per IP. The exact limits are visible in X-RateLimit-* response headers. Sane MCP and REST usage stays well within the limit; the goal is to stop runaway loops and scrapers, not real users.

If you hit the limit you'll get a 429 Too Many Requests with a Retry-After header. Wait, retry, you're back in.

Need higher quotas for a legitimate product? Reach out via our contact form. We'll work something out.

Registry listings

Eleven entries on the official MCP Registry under the com.whensport/* namespace, DNS-verified at whensport.com. Use the broad com.whensport/whensport for everything, or pull a single sport with one of the sport-specific entries.

• com.whensport/whensport — broad, all 10 sports
• com.whensport/wc-2026, com.whensport/f1-2026, com.whensport/tennis-2026, com.whensport/cricket-2026 — major-event listings
• com.whensport/polo, com.whensport/sailing, com.whensport/rugby, com.whensport/golf-majors — first dedicated MCP servers in their respective sport categories
• com.whensport/horse-racing, com.whensport/tour-de-france-2026

Roadmap

• v1.0 — 10 sports live (football, F1, tennis, cricket, rugby, golf, polo, sailing, horse racing, TDF). 48 MCP tools, REST mirrors. ✓
• v1.1 — Esports MCP (LoL, CS2, Valorant, Dota 2)
• v2 — Optional API keys for higher rate quotas, OpenAPI spec auto-generation, paid RapidAPI tier

Data source & canonical pages

Both the MCP and the REST API read from whensport's Brain — the same Cloudflare D1 database that drives every page on this site. When you call the API, you're getting the exact same canonical data a human visitor sees. Browse the WC schedule, or see Japan's localized schedule page as an example.

Support

Bug reports, feature requests, integration questions, or partnership conversations — use the contact form. Mention "API" or "MCP" in the subject so we route it correctly. Replies usually within 24 hours.

The MCP and REST API are maintained by larsen.studio. Source data ingestion runs every 30 minutes; if you spot stale or wrong data, the form above is the fastest fix.