MatchDay

Never miss a World Cup moment. An AI agent that tracks your teams, delivers live match data, sets personalized reminders, and answers host city venue questions — powered by Gemini and MongoDB.

Comment

Inspiration

The 2026 FIFA World Cup is the first tournament to span three countries — the United States, Canada, and Mexico — with 48 teams across 16 host cities and 104 matches. For fans following multiple teams, this means juggling timezone math, cross-country travel logistics, venue research, fantasy predictions, and match reminders across half a dozen apps and websites.

I wanted to see if a single conversational AI agent could replace that fragmented experience. Not a chatbot that answers questions — an agent that actually does things: persists your preferences, plans your trips, fires reminders, and tracks your predictions.

What it does

MatchDay is a multi-tool AI agent that handles the full World Cup 2026 fan experience through natural language:

  • Live match data — schedules, results, standings, team info from ESPN's live API
  • Team following — persistent state in MongoDB Atlas via the MongoDB MCP server
  • Match reminders — set personalized timing, delivered via email by a background scheduler
  • Trip planning — chronological itineraries that chain match schedules with venue knowledge
  • Fantasy predictions — score predictions with automated grading (3 points exact, 1 point correct winner) and a multi-user leaderboard
  • Head-to-head queries — historical matchup data via Gemini's grounded Google Search
  • Tournament bracket — full schedule view with venues, grouped by date
  • Conversation memory — agent remembers context across turns

How I built it

The agent runs on Gemini 3.1 Pro Preview via Vertex AI, orchestrated by a custom Python tool-calling loop using the google-genai SDK. FastAPI serves the chat API and HTML frontend, deployed as a container on Cloud Run.

The tool layer:

  • ESPN API for live match data
  • MongoDB MCP server (partner track) for all user state — reads via MCP find, writes via update-many, insert-many, delete-many, and a $group aggregation for the leaderboard
  • Google Cloud Discovery Engine as a RAG knowledge base for venue and host city information, populated from curated text documents in Cloud Storage
  • Gemini grounded search for head-to-head historical queries

A separate asyncio background worker runs every 30 seconds, queries MongoDB for due reminders, and dispatches emails via Brevo SMTP relay. Secrets are managed through GCP Secret Manager.

Challenges I ran into

MongoDB MCP write failures on Cloud Run. Reads worked fine, but every write returned "connection string not valid." I spent hours debugging the URI format, the env var passing, and the MCP server's argument parsing. The actual root cause turned out to be Atlas's IP access list — only my local IP was whitelisted, blocking Cloud Run's egress entirely. One network rule change fixed everything. A reminder that production issues with cryptic messages are often infrastructure problems disguised as code problems.

Background workers on Cloud Run. Cloud Run throttles CPU between requests by default, which silently kills background asyncio tasks. Adding --no-cpu-throttling to the deploy command keeps the reminder worker active and ticking.

Team name aliases. ESPN's API uses "United States" not "USA", "Türkiye" not "Turkey". Without normalization the agent would return empty results for common shorthand. A small alias map fixed it cleanly.

What I learned

The most valuable lesson was about agent design boundaries. The first version of the agent would happily save "Wakanda" as a followed team, fabricate weather data for Tokyo, and invent World Cup matches that don't exist. None of these were code bugs — they were system instruction gaps. Updating the agent's system prompt to validate inputs against real data sources and refuse out-of-scope queries fixed all three behaviors without writing any new code. Agent guardrails are a prompt engineering problem more than a code problem.

I also got hands-on with the Model Context Protocol for the first time. MCP feels like the right abstraction for AI agents that need to talk to external services — you describe tools once and any MCP-compatible client can use them. The MongoDB MCP server gave me 29 tools out of the box without writing any database integration code.

What's next

  • More MCP integrations — Slack for match notifications, Calendar for trip itineraries
  • Voice interface — Gemini's audio capabilities for hands-free use during matches
  • Cross-tournament expansion — same architecture for Champions League, Copa America, Euros
  • Group chat mode — multi-user prediction leagues with friends

Built With

Share this project:

Updates