Start branch: lab/05-start
Solution tag: lab/05a-solution
Session replay: labs/05a/session.jsonl
Objective
Design an MCP (Model Context Protocol) tool server from scratch. Pick a domain, write a PRD, decompose into wave-quality issues, and plan parallel execution — all before writing a single line of implementation code.
This lab teaches the design phase of the workflow. Lab 05b continues with execution.
Prerequisites
What is MCP?
The Model Context Protocol lets you give Claude Code new capabilities by building tool servers. Your server runs locally, communicates over stdio, and exposes tools that Claude can call during a session. Think of it as writing plugins for your AI assistant.
The start branch includes a scaffold: an empty MCP server that starts, responds to tools/list with nothing, and exits cleanly. Your job is to design what it should actually do.
Steps
Step 1: Pick your domain
Do: Think about what tools would be useful to YOU in a Claude Code session. Some ideas:
- A server that queries your todo list, calendar, or notes app
- A server that looks up documentation for your team's internal APIs
- A server that runs database queries and formats results
- A server that manages git worktrees or branch housekeeping
- A server that interacts with a local service (Home Assistant, Pi-hole, etc.)
Tell Claude what you want to build. Discuss scope — aim for 2-3 tools, not 10.
Verify: You can describe your server in one sentence: "An MCP server that ____"
Learn: Scoping is the hardest part of design.
Step 2: Write the PRD
Do: Work with Claude to write a PRD using the template in docs/PRD-template.md. Cover tools, configuration, testing, and success metrics.
Verify: Your PRD has: Summary, Tools section with schemas, Test Plan, and Success Metrics
Learn: A PRD is a contract between you (the designer) and the agent (the implementer). Vague PRDs produce vague code.
Step 3: Decompose into issues
Do: Work with Claude to dice the PRD into implementation issues. Each should follow the story template with Implementation Steps, Test Procedures, and Acceptance Criteria. Aim for 4-6 issues across 2-3 waves.
Verify: Each issue is wave-quality — an agent could execute it without asking questions
Learn: Wave-quality specs mean the agent never has to make design decisions.
Step 4: Map dependencies and plan waves
Do: Run /prepwaves with your master issue. Review the dependency graph and wave plan.
Verify: /prepwaves produces a wave plan with at least 2 waves and some parallelism
Learn: Dependencies determine wave order. Independent issues run in parallel.
Step 5: Review and approve
Do: Read through the wave plan and approve it.
Verify: You've approved the /prepwaves plan
Learn: This is the last gate before agents start writing code. If the plan is wrong, the code will be wrong — faster.
You Learned
What's Next
Continue to Lab 05b: Build and Ship It to execute your plan with /nextwave.
Stuck?
Load labs/05a/session.jsonl into Clawback to watch an example design session for a dice-roller + unit-converter MCP server.
Start branch:
lab/05-startSolution tag:
lab/05a-solutionSession replay:
labs/05a/session.jsonlObjective
Design an MCP (Model Context Protocol) tool server from scratch. Pick a domain, write a PRD, decompose into wave-quality issues, and plan parallel execution — all before writing a single line of implementation code.
This lab teaches the design phase of the workflow. Lab 05b continues with execution.
Prerequisites
install.sh --checkall green)What is MCP?
The Model Context Protocol lets you give Claude Code new capabilities by building tool servers. Your server runs locally, communicates over stdio, and exposes tools that Claude can call during a session. Think of it as writing plugins for your AI assistant.
The start branch includes a scaffold: an empty MCP server that starts, responds to
tools/listwith nothing, and exits cleanly. Your job is to design what it should actually do.Steps
Step 1: Pick your domain
Do: Think about what tools would be useful to YOU in a Claude Code session. Some ideas:
Tell Claude what you want to build. Discuss scope — aim for 2-3 tools, not 10.
Verify: You can describe your server in one sentence: "An MCP server that ____"
Learn: Scoping is the hardest part of design.
Step 2: Write the PRD
Do: Work with Claude to write a PRD using the template in
docs/PRD-template.md. Cover tools, configuration, testing, and success metrics.Verify: Your PRD has: Summary, Tools section with schemas, Test Plan, and Success Metrics
Learn: A PRD is a contract between you (the designer) and the agent (the implementer). Vague PRDs produce vague code.
Step 3: Decompose into issues
Do: Work with Claude to dice the PRD into implementation issues. Each should follow the story template with Implementation Steps, Test Procedures, and Acceptance Criteria. Aim for 4-6 issues across 2-3 waves.
Verify: Each issue is wave-quality — an agent could execute it without asking questions
Learn: Wave-quality specs mean the agent never has to make design decisions.
Step 4: Map dependencies and plan waves
Do: Run
/prepwaveswith your master issue. Review the dependency graph and wave plan.Verify:
/prepwavesproduces a wave plan with at least 2 waves and some parallelismLearn: Dependencies determine wave order. Independent issues run in parallel.
Step 5: Review and approve
Do: Read through the wave plan and approve it.
Verify: You've approved the
/prepwavesplanLearn: This is the last gate before agents start writing code. If the plan is wrong, the code will be wrong — faster.
You Learned
What's Next
Continue to Lab 05b: Build and Ship It to execute your plan with
/nextwave.Stuck?
Load
labs/05a/session.jsonlinto Clawback to watch an example design session for a dice-roller + unit-converter MCP server.