A Next.js application that makes AI decision-making visible. Type a natural language query and watch the system reason through candidate matching in real-time — filtering and ranking 50+ candidates with full explainability at every step.
MCP Orchestration Workflow
Candidate Profiles
LLM Provider
The app routes every natural language query through a four-stage MCP pipeline. The LLM first generates structured filter and ranking plans (THINK), the core tools execute filtering and scoring against the CSV dataset (ACT × 2), then the LLM synthesises results into a human-readable summary (SPEAK). Each stage is streamed to the UI in real-time so users can watch the reasoning unfold.
FIGURE A.01
Four-Stage MCP Pipeline
Getting the LLM to consistently emit valid filter and ranking plans as structured JSON — without hallucinating fields or breaking the downstream tool calls.
Used AI SDK's structured output mode with strict Zod schemas for both the filter plan and ranking plan. Any schema violation triggers a retry with an error-context prompt, keeping the pipeline deterministic.
Showing each pipeline stage (Think / Act / Speak) as it completes — without blocking the UI or faking progress.
Streamed stage completion events from the API route using Server-Sent Events. Each stage posts its result as it resolves, letting the frontend animate the timeline in true real-time with Framer Motion staggered transitions.
Building a transparent AI workflow taught me that explainability is an engineering problem, not just a product feature.
Defining strict Zod schemas before writing a single prompt eliminated an entire class of runtime errors and made the LLM's output predictable.
Server-Sent Events for pipeline stage updates gave a dramatically better UX than polling — users see progress immediately rather than waiting for the full result.
Keeping filtering, ranking, and summarisation as distinct tool functions made each individually testable and easy to swap out.
Showing the AI's reasoning steps reduced perceived uncertainty — users trusted the results more when they could see how they were produced.
Brian Mutai / Full-Stack Engineer