# Learn MCP > An interactive lesson that teaches the Model Context Protocol (MCP) by building a real, working MCP server from scratch. Use this skill whenever the user wants to learn MCP, understand MCP concepts (host, client, server, tools, resources, prompts, transport), asks "what is MCP" or "how does MCP work", wants to build an MCP server, mentions building a database-backed or HTTP MCP server, or asks for an MCP tutorial, walkthrough, or hands-on guide. Trigger this even if the user only says something like "teach me MCP", "I want to build an MCP server", or "explain MCP tools vs resources" — they want this guided lesson, not a one-line answer. - Skill: `ffoysal/learn-mcp` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add ffoysal/learn-mcp` - Raw SKILL.md: https://api.skillmd.com/api/skills/ffoysal/learn-mcp/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: ffoysal (https://skillmd.com/u/ffoysal) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/ffoysal/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.