GemScout

AI scouting agent that finds World Cup 2026 hidden gems using natural language — powered by Gemini, MongoDB Atlas Vector Search, and 2,200+ players across global leagues.

Comment

Inspiration

The 2026 World Cup is the biggest football tournament in history — 48 nations, an expanded format, and transfer windows that close before the tournament starts. We kept thinking about the same impossible problem facing every sporting director, club analyst, and agent right now: how do you evaluate 2,200+ players across dozens of leagues, identify the hidden gems before anyone else, and make decisions worth millions of euros — in weeks, not months?

Traditional scouting tools are dashboards with filters. Powerful, yes — but they require you to already know what you're looking for. You can't ask a slider "find me a box-to-box midfielder with a Modrić-like profile, under 24, playing outside the top 5 leagues" and expect a real answer.

The inspiration was simple: a filter can't answer that. An agent can.

What it does

GemScout is an AI scouting agent — not a search engine, not a dashboard.

You describe what you need in plain language. The agent reasons over 2,200+ real player profiles indexed in MongoDB Atlas, executes multiple tool calls through the official MongoDB MCP server, and streams back a full scouting dossier in real time.

Core capabilities:

  • Natural language scouting — describe a tactical profile; the agent figures out how to find it across the database
  • Live reasoning trace — every MongoDB MCP tool call is visible as it happens; the agent thinks in front of you
  • Token-by-token dossier streaming — SSE end-to-end from Google ADK through FastAPI to the browser
  • Find Similar — one click on any player card runs $search moreLikeThis against Voyage AI embeddings to find tactically similar profiles across the entire database
  • 3-season World Cup cycle analysis — historical data from 2023-24 and 2024-25 lets the agent identify players who are peaking right now, heading into the tournament
  • Judges Panel — a technical transparency layer exposing every raw MCP tool call, MongoDB pipeline, and ADK reasoning step for full auditability

How we built it

Agent layer

Google ADK (google-adk[mcp]==2.0.0) orchestrates an LlmAgent backed by gemini-3.1-pro-preview on Vertex AI. The agent receives the natural language query, decides which MongoDB operations to run, iterates over results, and writes the final scouting dossier.

Partner integration

The official @mongodb-js/mongodb-mcp-server runs as a dedicated Cloud Run service, connected to the ADK agent via SSE transport. Every find and aggregate the agent executes goes through this MCP server — this is the core partner integration, and it's not cosmetic. The agent genuinely uses it to reason over live data.

Data layer

MongoDB Atlas holds 2,200+ player documents with raw stats (xG, xA, pressing metrics, GK-specific), percentile normalization within position groups, a profile_text natural language tactical description per player, Voyage AI voyage-3-large embeddings (1024-dim) for semantic similarity, and history subdocuments covering three full seasons.

Streaming pipeline

User query
  → FastAPI /agent/scout/stream
  → ADK /run_sse (Gemini 3.1 Pro, Vertex AI)
  → MongoDB MCP Server (SSE transport, Cloud Run)
  → MongoDB Atlas — find / aggregate / $search moreLikeThis
  → SSE events: step_start / player / text / done
  → React 19 UI — live reasoning trace + streaming dossier

Four services on Cloud Run — fully deployed, publicly accessible

Service Role
gemscout-frontend React 19 + TypeScript + Nginx reverse proxy
gemscout-backend FastAPI — SSE orchestration, player API
gemscout-agent Google ADK (adk api_server)
gemscout-mcp @mongodb-js/mongodb-mcp-server (official partner MCP)

Challenges we ran into

SSE end-to-end streaming was harder than expected. Getting true token-by-token streaming from ADK's /run_sse through FastAPI and Nginx to the browser required careful configuration — proxy_buffering off in Nginx, chunked transfer encoding headers, and a custom SSE event parser on the React side. When it finally clicked, watching the agent reason live in the browser was genuinely exciting.

MCP transport in a multi-service Cloud Run environment. Running the MongoDB MCP server with SSE transport as a remote service — with the ADK agent as the client — required careful handling of connection lifecycle, timeout configuration, and error recovery. The official server is robust, but wiring it up across Cloud Run services took real iteration.

Atlas Search index propagation. MongoDB Atlas Search indexes aren't instant after deployment. During rapid iteration cycles, waiting for index propagation on the player_text_index and the vector index added friction that required us to build better local testing workflows.

Data coverage scope. Our dataset covers the Big-5 European leagues. South American players are indexed based on their current European club — meaning a Brazilian playing in Serie A is included, but a player still in the Brasileirão is not. Expanding to CONMEBOL, CONCACAF, and Liga MX would significantly strengthen the World Cup hidden gem narrative.

Accomplishments that we're proud of

  • The agent genuinely reasons — it doesn't just retrieve; it iterates, refines queries, and writes analytical dossiers that a human scout would recognize as useful
  • Atlas Search + Vector Search on a single platform — having find, aggregate, and $search moreLikeThis all accessible through the same MCP server made the dual-mode search (structured + semantic) surprisingly clean to implement
  • Streaming UI that changes the feel of AI — watching reasoning steps appear live, then player cards stream in, then the dossier write itself token by token transforms the experience from "waiting for a result" to "watching intelligence work"
  • A real dataset — 2,200+ players with three seasons of historical data, Voyage AI embeddings, and percentile normalization, all built from scratch for this project
  • Deployed and public — four Cloud Run services, live, accessible to anyone with the URL

What we learned

MCP is the right abstraction for agentic data access. Watching Gemini decide which MongoDB query to run, execute it through the MCP server, inspect the results, and iterate — without any hardcoded query logic on our side — validated the architecture in a way that's hard to appreciate until you see it working.

MongoDB Atlas Search and Vector Search on the same cluster eliminates a whole class of complexity. Not having to maintain a separate vector database, a separate search index, and a separate operational store — and having all of them accessible through a single MCP server — made the system dramatically simpler than we expected.

Transparency matters in agentic systems. The Judges Panel — showing every raw MCP call and MongoDB pipeline — wasn't in the original spec. We added it because we realized that without it, the agent's intelligence is invisible. Making the reasoning auditable turned out to be as important as the reasoning itself.

What's next for GemScout

  • Global data coverage — CONMEBOL, CONCACAF, Liga MX, and Eredivisie to make the hidden gem narrative truly global for the World Cup
  • Real-time market value tracking — integrating transfer market data so the agent can reason about value inefficiencies in real time
  • Multi-agent architecture — separate Scout Agent and Analyst Agent for deeper, more specialized dossiers
  • Squad gap analysis — given a national team's current roster, automatically identify the top 3 players who fill the biggest tactical hole
  • Alert system — subscribe to a player profile; get notified when a statistically similar player emerges in the database

GemScout. Find them first.

Built With

Share this project:

Updates