whensport API & MCP

Two surfaces, same data

MCP server

One endpoint, 10 sports, 46 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

• WC 2026 — getCountrySchedule, getTeamMatches, getMatch, findToday, getCurrentlyLive, getCountryList
• F1 — f1.getRaces, f1.getRace, f1.getNextRace, f1.getDrivers, f1.getTeams
• Tennis — tennis.getTournaments, tennis.getTournament, tennis.getNextGrandSlam, tennis.getVenues, tennis.getPlayers
• Cricket — cricket.getTournaments, cricket.getTournament, cricket.getMatches, cricket.getMatch, cricket.getPlayers
• Rugby — rugby.getTournaments, rugby.getTournament, rugby.getMatches, rugby.getMatch
• Golf Majors — golf.getTournaments, golf.getTournament, golf.getNextMajor, golf.getVenues, golf.getPlayers
• Polo — polo.getTournaments, polo.getTournament, polo.getVenues, polo.getTeams, polo.getPlayers
• Sailing — sailing.getEvents, sailing.getEvent, sailing.getVenues, sailing.getTeams
• Horse Racing — hr.getMeetings, hr.getMeeting, hr.getVenues
• Tour de France — tdf.getStages, tdf.getStage, tdf.getStagesInRange, tdf.getRacePhase

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

Test the MCP from a terminal

# List available tools (broad endpoint, all 46)
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 from the broad endpoint
curl -X POST https://whensport.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"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? Email Sebastian. 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). 46 MCP tools, REST mirrors. ✓
• v1.1 — Esports MCP (LoL, CS2, Valorant, Dota 2) sourced from whenesport.com
• 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.