expert-answer-mcp

An MCP server exposing one tool, get_expert_verified_answer — ask it "what is LangChain?" or "what is Mosaic?" and it answers as an expert verifier, backed by Gemini.

Live demo: add the Render URL here once deployed (see docs/CONVENTIONS.md §8.2 — the free-tier service will be asleep on first click; give it ~50s to wake up). Screenshot/GIF: add one of the web page or an MCP client call here before treating this README as finished — a reviewer should see the thing work before reading further.

Why it's interesting

• One tool, three clients. The same tool is reachable from Claude Desktop (MCP stdio), any MCP SDK client (streamable HTTP — see clients/mcp_client_demo.py), and a plain browser form. Proving client-agnosticism, not building a tool catalogue, is the point.

• Honest scope trade-offs. No Postgres, no audit log, no rate limiting, no circuit breaker — see docs/adr/0001-minimal-scope.md for why, stated as a decision rather than left to look like an omission.

• Deterministic, quota-safe repeats. A content-addressed in-memory cache means asking the same question twice doesn't call Gemini twice (docs/adr/0003-in-memory-cache.md).

Related MCP server: Gemini Google Web Search MCP

Architecture

See docs/ARCHITECTURE.md for the diagram, ADR index, and constraint table.

Quickstart

git clone <this-repo>
cd expert-answer-mcp
cp .env.example .env   # fill in a real GEMINI_API_KEY
docker compose up

Then open http://127.0.0.1:8000/ to ask a question in the browser.

Connecting Claude Desktop

Copy clients/claude_desktop_config.json into Claude Desktop's MCP config, fixing the command/cwd absolute paths and GEMINI_API_KEY for your machine.

Running the standalone MCP client demo

.venv/bin/uvicorn app.main:app --port 8000 &
.venv/bin/python clients/mcp_client_demo.py

Note: the server's client-facing MCP endpoint is /mcp/mcp, not /mcp — app/main.py mounts the MCP sub-app at the /mcp prefix, and that sub-app has its own default /mcp route (this is intentional, per the mcp SDK's mounting behavior; see docs/ARCHITECTURE.md). If you connect your own MCP client to plain /mcp you'll get a 404 — use /mcp/mcp.

Testing

.venv/bin/pytest

Unit tests cover the domain logic with no I/O; integration tests cover the MCP tool registration, the web routes, and a real MCP client talking to a real running server — no test calls the live Gemini API (see docs/CONVENTIONS.md).

Limitations

• Cache is in-memory only — cleared on restart (a deliberate trade-off, not a bug).

• "Expert-verified" is a prompt-framing decision (one Gemini call), not a second verification pass.

• No rate limiting or multi-tenancy — this is a single-key portfolio demo.