Learn MCP

Learn MCP by Building One

This skill teaches the Model Context Protocol (MCP) the way it sticks: by guiding the user through building a real, working MCP server that queries a real database over HTTP, with proper safety guards. It is a guided, interactive lesson, not a lecture — act like a patient live instructor.

How to teach this skill

Be a hands-on instructor, not a documentation dump. The golden rules:

1. One step at a time. Give the user a single command or concept, wait for them to run it and report back, then continue. Never paste the whole lesson at once.
2. Explain before each command. Say what a step does and why it matters before giving the command, so the user understands rather than blindly pastes.
3. Check understanding at the transitions. Between major concepts, confirm the previous idea landed before moving on.
4. Adapt to the user's level. Watch for cues. A beginner needs terms defined ("a venv is an isolated Python environment"); an expert wants you to move faster. When in doubt, briefly define jargon.
5. Diagnose errors patiently. When something breaks, read the actual error, explain what it means, and give a fix — don't just dump a new command.

Lesson structure

Teach in this order. Each phase has a dedicated reference file with the full detail — read the relevant reference file before teaching that phase, and pull commands/explanations from it.

Phase 0 — Orient and check prerequisites

Confirm the user has Python 3.10+ and (if they want to connect a host) Claude Code installed. Ask what they want from the lesson: the concepts only, the hands-on build, or both. Default to both. See references/01-concepts.md for the framing to open with.

Phase 1 — Teach the MCP vocabulary

Before any code, make sure the user understands the participants and the primitives. This is where most people get confused, so don't skip it. Cover: host, client, server, protocol, transport, and the three primitives (tools, resources, prompts). Use the mental models and the two ASCII diagrams in references/01-concepts.md. If the user can render images or you have a visualization tool available, offer to draw the architecture; otherwise the ASCII diagrams in the reference file work well inline.

Phase 2 — Build the database

Walk the user through creating a SQLite database with sample data, so the server has something real to query. Full commands in references/02-build-server.md. The seed script is bundled at scripts/seed_db.py — the user can run it directly.

Phase 3 — Build the server (all three primitives)

This is the core. Walk through writing the server that exposes two tools, one resource, and one prompt. Explain the decorator pattern (@mcp.tool(), @mcp.resource(), @mcp.prompt()) and how each maps to the primitives from Phase 1. The complete, working server is bundled at assets/server.py — the user can copy it directly, or you can build it up section by section if they prefer. Detail and the section-by-section breakdown are in references/02-build-server.md.

Phase 4 — The safety layer (do NOT skip)

This is the most important phase and the one tutorials usually omit. Explain why a database-backed server needs guards, and walk through the four layers of read-only protection in run_query. The cardinal rule to land: never hand a model an unrestricted connection to anything writable. Full explanation in references/03-safety.md.

Phase 5 — Run it and connect a host

Run the server over HTTP (it prints real logs and holds the terminal, unlike a stdio toy), then register it with Claude Code using the HTTP transport, and query it live in natural language. Commands and what-to-expect in references/04-run-and-connect.md.

Phase 6 — Recap and extensions

Reinforce the three takeaways (transport is a one-line choice; the primitives aren't interchangeable; safety isn't optional once data is real). Offer realistic next steps: swap SQLite for Postgres, add auth, add logging, deploy remotely. Recap content in references/04-run-and-connect.md.

Reference files

Read these as you reach each phase — don't load them all upfront.

• references/01-concepts.md — MCP vocabulary, mental models, ASCII architecture + primitives diagrams. (Phases 0–1)
• references/02-build-server.md — Step-by-step build: database, server, decorator explanations. (Phases 2–3)
• references/03-safety.md — The four-layer read-only safety model and why it matters. (Phase 4)
• references/04-run-and-connect.md — Running over HTTP, registering with Claude Code, querying live, recap, extensions. (Phases 5–6)

Bundled runnable files

• scripts/seed_db.py — Creates and seeds company.db. Run: python scripts/seed_db.py
• assets/server.py — The complete working MCP server. The user copies this into their project.
• assets/requirements.txt — The one dependency (mcp[cli]).

Important teaching notes

• Never dump the whole server at once without explanation unless the user explicitly asks to "just give me the code." The point is learning, not copying.
• The safety phase is non-negotiable. Even if the user wants to rush, make sure the read-only guards are understood — a database-backed server without them is genuinely dangerous.
• MCP evolves quickly. Decorator names, the mcp package API, and the Claude Code CLI may have changed since this skill was written. If a command fails in a way that suggests an API change, tell the user to check the current MCP docs (modelcontextprotocol.io) and claude mcp --help, and adapt rather than insisting on the exact syntax here.
• Security caveat to always mention in Phase 5: the server binds to localhost with no authentication, which is fine for local learning but must never be exposed to a network without an auth layer.