How to use the Learn MCP Tutor agent skill (learn-mcp)

What the learn-mcp skill makes the agent do

Each time you invoke the skill, the agent teaches one lesson from the MCP learning path in the AI Engineering from Scratch repository. The path focuses on building, securing, debugging, verifying and operating MCP clients, servers, transports, gateways, registries and conformance gates.

During a lesson the agent asks you to inspect a request and response, predict a boundary result, and then run or hand-trace a small lab exercise. It records what was run in a progress file named MCP-LEARNING.md in your working directory, including the exit codes and observed results. The skill is a course tutor, not a tool that connects you to an existing MCP server.

Install the learn-mcp skill

Download the ZIP from the skill's page on our directory and unzip it. The skill's main file is SKILL.md. Place the folder in one of these locations, depending on how you want to use it:

• For all your projects: unzip into ~/.claude/skills/
• For one project only: unzip into the project's .claude/skills/ folder
• In the Claude apps: upload the skill under Settings, then Capabilities, then Skills

Start or resume the MCP path with a request

How you invoke the skill depends on your host. The skill's own instructions list these forms. In Claude Code, type the slash command. In Codex, name the skill or choose it from the /skills list. In other compatible hosts, ask in plain words.

If you have never run it, start with the first lesson. The skill resumes from your progress file if one already exists, so you can close the session and continue later.

• Claude Code: /learn-mcp
• Codex: learn-mcp, or choose it from /skills
• Other compatible hosts: Use learn-mcp to start or resume the Model Context Protocol (MCP) path.

What a typical lesson looks like

On the first invocation the agent begins Lesson 06 right away. If the lesson code is available locally and Python 3 is installed, it runs the lesson script from the repository root. You are then asked to point out the repeated protocol version and client capabilities, the complete server/discover result, error -32022, and the absence of protocol-session creation or teardown.

If the command cannot run, the agent switches to conceptual mode. It walks through one modern request and response from the lesson, asks you to label each envelope field, and marks the result as Conceptual rather than as an executed pass.

• Predict what the server will return before looking at the output
• Inspect a real request and response, or hand-trace one if you cannot run code
• Record the checkpoint before moving to the next lesson

Track progress in MCP-LEARNING.md

The progress file lives in the directory you run the skill from. It holds a route summary, an environment check, a public deployment gate, a table of 17 required lessons with status and evidence columns, a wire evidence log, and a notes section. The lesson order is 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 18, 17, 28, 29, 30 and 31. Lesson 18 comes before Lesson 17, so do not expect plain numeric order after Lesson 16.

If you already have a file under the older name MCP-ENGINEERING-LEARNING.md, the skill renames it to MCP-LEARNING.md before teaching, without changing your notes or evidence rows. If both files exist, it stops and asks which one should be updated. Lesson 23 is an optional capstone, offered only after Lessons 19 and 20 are complete.

• Status values include Next, In progress, Done and Locked
• Evidence is labelled Executable or Conceptual; checks you cannot run stay Pending

Safety: scripts, network and public deployment

The skill runs local Python commands in your working directory and writes MCP-LEARNING.md there. It may fetch lesson files from raw.githubusercontent.com when no local clone exists. It will not clone the repository until you confirm the destination directory. Redaction rules tell the agent to remove tokens, secrets, cookies, authorization headers and sensitive parameter values from its evidence log.

The lesson screen is optional. It needs Node.js 20 or later and a browser on your machine, and the agent offers it once per session. Before any public deployment, such as a non-loopback bind or hosted endpoint, the skill requires an executable Lesson 15 checkpoint, a reviewed threat model, and your explicit confirmation. Invoking the skill does not grant network, credential, publishing or deployment permission.

• Read the code in code/ before running anything if you are unsure what a script does
• Do not put real credentials in your notes or in the working directory

Tips for getting the most from the path

Run the lessons in executable mode if you can, because the wire evidence you record is more useful than a hand trace. Keep one working directory for the whole path so the progress file stays in one place. Use the notes section for your own observations, since the skill preserves them when it resumes.

If you cannot install Python 3 or clone the repository, you can still complete the conceptual route. Just remember that those checkpoints are recorded as Conceptual and the runtime checks stay Pending.

• Start each session with the same working directory
• Keep your own notes in the Notes section, not in the evidence table
• Use the optional TypeScript runner for Lesson 07 only if you want the second implementation