Study Sprint MCP

Five Claude agents build a fact-checked lesson for any subject, Kindergarten to College, reaching every tool through a Model Context Protocol server. The same server gives learners their lessons inside Claude Desktop and Claude Code.

This is the MCP edition of Study Sprint. The agents, rules and web app are the same. Their tools now live in an MCP server, wrapped in capability tokens, tool pinning, a guardrail hook pipeline, and a cost ledger that prices every tool in tokens and dollars.

→ How it works: 15-page PDF with charts and commentary · MCP design · Evals · Original guide with screenshots

Results

What MCP costs:

• Tokens: zero. The model reads byte-identical tool definitions on both transports (3,012 definition tokens across the five agents, confirmed by count_tokens).
• Time per tool call: about 1.8 ms.
• Start-up: about 2.8 s, once per process.

Over a 55-second build, that adds roughly 25 ms (0.05%). Details: section 7 of the PDF.

Quick start

python -m venv .venv
.venv\Scripts\python.exe -m pip install --no-cache-dir -r requirements.txt -e .
.\run.ps1 serve --demo                     # sample lessons, no API key -> http://127.0.0.1:8000
.\run.ps1 build "volcanoes" --grade 4      # live agents, tools over MCP (needs ANTHROPIC_API_KEY, ~$0.20)

Learn in Claude Code: open this folder in Claude Code and approve the study-sprint server from .mcp.json. Then ask "List my Study Sprint lessons and quiz me on the water cycle." Claude Desktop setup is in docs/mcp.md.

How it works

flowchart LR
    subgraph app [Direction 1: agents build lessons]
      H[Harness<br/>code decides the flow] --> A[5 Claude agents]
      A -- tool_use --> HK{{"Hook pipeline<br/>schema · no_model_cap · call_limit<br/>result_size · injection_scan · cost_cap"}}
      HK --> C{{"MCP client<br/>tools.lock.json pinning · protocol allowlist<br/>cap injection · byte + latency metering"}}
      C -- JSON-RPC / stdio --> S{{"Authoring MCP server<br/>capability token per agent · harness key<br/>40-call budgets · extra=forbid"}}
      S --> L[tool_logic.py<br/>same rules as direct]
      H -- open / export / close --> S
    end
    subgraph learn [Direction 2: learners study]
      CD([Claude Desktop / Code]) --> G{{"guard.py PreToolUse hook"}} --> LS{{"Learner MCP server<br/>read-only · public views · id regex"}}
      LS --> R[(runs/*/lesson.json)]
    end
    classDef guard fill:#fff4d6,stroke:#b45309,color:#78350f
    class HK,C,S,G,LS guard

Amber hexagons are guardrails.

• Code decides the flow; agents write the content. The harness runs the topic gate and orders the stages. After every stage it pulls the validated state back from the server and re-checks it with its own hand-off validators.
• One flag for the A/B. --transport mcp|direct changes only how tools are reached. Both transports run the same logic module, schemas, prompts and hook pipeline.

The two MCP profiles

Token cost per tool (live, mean per lesson over 27 MCP lessons)

How each column is measured:

• Definition tokens are exact, from messages.count_tokens (leave-one-out per agent), and paid at cache prices after the first turn.
• Decision tokens are the output of the turn that called the tool. They dominate: the Diagram Agent writes a whole SVG as a tool argument.
• Result tokens are small by design: tools answer in a sentence, not a document.

Commands

Always use the launcher. It keeps Python's bytecode cache and Playwright's browsers inside the project, as the CLAUDE.md guardrails require. On macOS or Linux, use ./run.sh.

Documentation

Project layout

studysprint/          the app (from Study Sprint); tool_logic.py is the single source of the agents' tools
  agents/runtime.py     agent loop with four hook points (pre/post model, pre/post tool)
  harness.py            pipeline, transports, hand-off validators, manifest
studysprint_mcp/
  server.py             MCP server: authoring and learner profiles (stdio)
  mcp_client.py         session thread, pinning, schema conversion, cap injection, metering
  hooks.py  guards.py   the hook pipeline and its six guards
  ledger.py             token costs per tool, MCP costs, overhead
  tools.lock.json       pinned tool definitions
evals/                content scorers + 5 MCP scorers, red-teams, conformance, parity, benchmark, live runner
tests/                269 tests (scripted fake Claude; real stdio MCP where it matters)
docs/build_report.py  the PDF, built from evals/results/
.mcp.json  .claude/   Claude Code: learner server + PreToolUse guard hook

License

MIT