Technical architecture.
Agent proof showing the run flow.
Generated plan for businesses.
Main interface.

Matchday Surge Agent

Inspiration

Major sports matchdays do not only affect stadiums.

They affect the small businesses around them: restaurants, markets, parking operators, and neighborhood services that suddenly have to handle more people, more questions, more lines, and more operational pressure than a normal day.

The problem is not just “more customers.” It is coordination.

A restaurant needs staffing, prep, queue flow, and multilingual messages. A market needs fast-moving items stocked before the rush. A parking operator needs lane flow, QR payment signage, pedestrian safety, and rideshare guidance.

Large operators plan for these moments. Small local businesses usually do not have that kind of operations support.

Matchday Surge Agent gives them a simple way to prepare before pressure arrives:

MongoDB MCP memory → Gemini planning → owner-approved brief.

The agent can recommend. The owner decides.

What it does

Matchday Surge Agent is a web-based operations agent for local matchday businesses.

The workflow is simple:

Choose a business profile.
Generate a matchday readiness plan.
Review staffing, resources, flow, risks, and customer messages.
Approve the final staff-ready brief.

The demo includes three MongoDB-backed scenarios:

Business	Scenario
Harbor Grill LA	Restaurant rush
Pico Market	Market stockout risk
Metro Lot Crew	Parking flow pressure

When a run starts, the selected profile locks. The backend calls the MongoDB MCP tool server and uses load_matchday_context to retrieve the selected business profile, scenario, readiness template, and guardrails.

Gemini then generates a structured plan specific to that business. The result includes staffing recommendations, inventory or resource prep, service-flow adjustments, customer-facing messages in English, Spanish, and French, risk notes, and an owner checklist.

Once the owner approves the plan, the app saves an approval event in MongoDB and unlocks the final brief.

This is not an auto-publishing chatbot. It is a controlled operations workflow.

How we built it

The app is built with Next.js, React, TypeScript, and Tailwind CSS, with API routes handling the agent workflow.

MongoDB is the operational memory layer. It stores:

business_profiles
matchday_scenarios
readiness_templates
generated_plans
approval_events

The MongoDB MCP tool server exposes tools including list_matchday_profiles and load_matchday_context.

The most important tool is load_matchday_context. It retrieves the selected business profile, scenario, readiness template, and guardrails, then passes that context into Gemini. That makes the plan grounded in the selected business instead of being a generic prompt response.

The hosted app runs on Google Cloud Run. The deployment uses Google Cloud Secret Manager for the MongoDB connection string, and the repo includes a health endpoint and smoke test so judges can verify the runtime stack quickly.

The agent path is:

Owner selects business
        ↓
MongoDB MCP loads context
        ↓
Gemini generates structured plan
        ↓
Owner reviews recommendations
        ↓
Owner approves final brief
        ↓
Approval event is saved in MongoDB

Challenges we ran into

The first challenge was making the project more than a chatbot. I wanted the system to have memory, tool retrieval, review, and a final state change. The final workflow became: retrieve context, generate plan, require owner review, and save approval.

The second challenge was avoiding a one-scenario demo. Early versions were too restaurant-focused, so I expanded the app to support a restaurant, a market, and a parking operator. The parking scenario helped prove the agent can adapt to different operational pressures, not just food service.

The third challenge was reliability. Gemini sometimes returned imperfect structured JSON, so I added JSON response mode, lower temperature, validation, retry logic, and a deterministic fallback. That made the live demo safer and the system more judge-testable.

Deployment also required careful secret handling. The live Cloud Run app reads the MongoDB URI from Secret Manager, and the repo includes verification scripts to prove the hosted app, MongoDB MCP, Gemini live generation, and owner approval all work end to end.

Accomplishments that we're proud of

I am proud that this became a real deployed agent workflow, not just a prototype screen.

The project includes:

A live Google Cloud Run deployment
MongoDB MCP used at runtime through load_matchday_context
Gemini live generation of structured operations plans
Three distinct MongoDB-backed business scenarios
Owner review before finalization
Approval events saved back to MongoDB
Visible proof cards in the UI
A health endpoint for runtime proof
A smoke test that verifies the full deployed flow

I am also proud that the project stayed focused. It would have been easy to add maps, dashboards, forecasts, and extra visuals. Instead, I kept the product centered on one useful outcome:

A local business gets a clear matchday plan before the rush begins.

What we learned

The biggest lesson is that agents need visible structure.

A strong agent demo should not hide everything behind one button. The user and the judge should be able to see what context was retrieved, what the model generated, what guardrails exist, and what final action was taken.

I also learned that MCP makes the memory boundary cleaner. Instead of hardcoding every scenario into the app or stuffing everything into a prompt, the MCP tool server gives the agent a defined way to retrieve business context from MongoDB.

Finally, I learned that human approval is not a limitation. For this kind of product, it is the product. The goal is not to replace the owner. The goal is to help the owner prepare faster, review clearly, and act with more confidence before pressure arrives.

What's next for Matchday Surge Agent

Next, I would make the system useful for real local operators.

Planned improvements include:

A business setup flow so owners can create their own profiles
A run history page for approved briefs
Post-event feedback so future plans improve based on what actually happened
More business types, including food trucks, coffee shops, convenience stores, parking lots, and merch stands
Optional integrations for staff communication, signage templates, and reminders

The bigger vision is simple: