mcp-server-and-agent

Status: work in progress. Scaffolded, not yet implemented. This README will carry generated numbers once the first results land.

A hand-written MCP server at the protocol level plus a LangGraph agent over it, with four topologies run against the same task set and their failure modes measured.

This repo answers one question:

What is each agent topology's failure rate, and does supervisor actually beat single-agent?

Everything here serves answering that. Features that do not help answer it are out of scope — deliberately.

Why this exists

<!-- 2-4 sentences: what was hard, what this establishes. Written last. -->

Quickstart

uv sync --extra dev
uv run pytest -q
uv run python scripts/generate_results.py

Results

<!-- Generated by scripts/generate_results.py into results/. Every number carries: date, hardware, model snapshot, seed, reproduce command, and the raw artifact path. No number is typed by hand. -->

No results yet.

Design decisions

<!-- The judgement artifact for this repo: docs/failure-taxonomy.md: six failure modes with reproduction seeds and rate per topology. Supervisor costs 3x the tokens for no accuracy gain. -->

Limitations

<!-- At least one thing this repo does NOT establish. Written honestly. -->

Concepts covered

• 2C hand-written MCP server plus LangGraph agent (DO-8)
• 2C ReAct, plan-and-execute, reflection
• 2C topologies and their failure modes
• 2C tool design: schema clarity, granularity, errors as model feedback, idempotency, confirmation gates
• 2C MCP as a protocol: transports, discovery, resources, prompts, sampling, OAuth scope
• 2C state and memory, checkpointing, durable execution
• …and 4 more (see docs/inventory-coverage.md)

License

MIT