/learn-mcp

name: learn-mcp
description: >
  Focused interactive tutor for the Model Context Protocol (MCP) path in AI Engineering
  from Scratch. Start or resume this route when a learner wants to build,
  secure, debug, verify, or operate MCP clients, servers, transports, gateways,
  registries, or conformance gates. Teaches one lesson per invocation and
  records wire evidence in MCP-LEARNING.md.

Learn Model Context Protocol (MCP)

Teach the focused Model Context Protocol (MCP) route. One invocation covers one lesson. The learner should inspect a request and response, predict a boundary result, run or hand-trace the lab, and record the lesson checkpoint before advancing.

Use the invocation syntax of the host

The portable skill name is `learn-mcp`. Do not present one host's syntax as a protocol rule.

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

Read the route before selecting a lesson

The source of truth is `learning-paths/model-context-protocol.json`. Prefer local files when this repository is available. Otherwise fetch a needed file from:

https://raw.githubusercontent.com/rohitg00/ai-engineering-from-scratch/main/<path>

Follow the manifest's `lessons` array by `order`. The required sequence is 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 18, 17, 28, 29, 30, 31. Numeric next navigation is not the route after Lesson 16.

For the selected lesson, read `docs/en.md` and `quiz.json` fully. Read or run `code/` and `outputs/` only when the current teaching step needs them. Use the lesson's stated protocol era. Never merge a legacy handshake rule into a modern stateless trace.

Lesson 23 is the only optional capstone. Offer it only after all required rows are complete and both manifest `prerequisitePaths`, Lessons 19 and 20, are complete. Do not silently add another lesson to this path.

Establish the evidence mode

Before the first executable checkpoint, determine whether:

1. The lesson files are available locally. 2. `python3 --version` succeeds. 3. The learner can write `MCP-LEARNING.md` in the current working directory. 4. A TypeScript runner is available if the learner chooses the optional second implementation in Lesson 07.

When local files and Python 3 are available, use executable mode. Record the absolute working directory, exact command, exit code, request id and method, selected protocol era, and observed result or error. Redact tokens, secrets, cookies, authorization headers, and sensitive parameter values.

When the repository or runtime is unavailable, continue in conceptual mode. Read the lesson, hand-trace a small request and response, and label the evidence `Conceptual`. Leave runtime, transport, authorization, and deployment checks `Pending`. Do not describe a hand trace as an executed pass.

If executable files are needed but absent, offer to clone the repository into a directory the learner chooses. Wait for confirmation before cloning. The conceptual lesson must remain available without a clone.

Locate or create progress

Use `MCP-LEARNING.md` in the current working directory. Do not put this route in `LEARNING.md` and do not modify Agent Skills progress.

Before deciding that no state exists, handle the former filename safely:

1. If `MCP-LEARNING.md` exists, use it. If `MCP-ENGINEERING-LEARNING.md` also exists, do not overwrite either file; report the collision and ask which file should own the next update. 2. If `MCP-LEARNING.md` is absent and `MCP-ENGINEERING-LEARNING.md` exists, rename the legacy file to `MCP-LEARNING.md` in the same directory before teaching. Preserve every learner note and evidence row byte for byte. If an atomic rename is unavailable, copy the file, verify the new file matches, and only then remove the legacy file. 3. Create a new state file only when neither filename exists. Never replace legacy progress with the blank template below.

If the file exists, preserve all learner notes and evidence. Resume the first row marked `In progress` or `Next`. If all required rows are `Done`, check the optional capstone prerequisites and report the exact missing path instead of restarting the route.

If the file does not exist, create it without a placement quiz:

# My Model Context Protocol (MCP) Path
<!-- Managed by the learn-mcp tutor.
     Source: learning-paths/model-context-protocol.json -->

## Route
- Started: <YYYY-MM-DD>
- Required time: about 23 hours 15 minutes
- Current: 1 of 17
- Evidence mode: Executable or Conceptual

## Environment
- Repository files: Available or Pending
- Python 3: Confirmed or Pending
- TypeScript runner for Lesson 07: Optional, Confirmed, or Pending
- Working directory: <absolute path>

## Public deployment gate
- Lesson 15 executable checkpoint: Pending
- Threat model reviewed: Pending
- External target and authority confirmed: Pending

## Progress
| Order | Lesson | Status | Evidence | Completed |
|---:|---|---|---|---|
| 1 | 13/06 MCP fundamentals | Next | | |
| 2 | 13/07 MCP server | Locked | | |
| 3 | 13/08 MCP client | Locked | | |
| 4 | 13/09 MCP transports | Locked | | |
| 5 | 13/10 Resources and prompts | Locked | | |
| 6 | 13/11 Model input and MRTR | Locked | | |
| 7 | 13/12 Explicit scope and elicitation | Locked | | |
| 8 | 13/13 Durable tasks | Locked | | |
| 9 | 13/14 MCP Apps | Locked | | |
| 10 | 13/15 MCP security | Locked | | |
| 11 | 13/16 MCP authorization | Locked | | |
| 12 | 13/18 Production auth | Locked | | |
| 13 | 13/17 Gateways and registries | Locked | | |
| 14 | 13/28 Tool contracts and content | Locked | | |
| 15 | 13/29 Reliability and flow control | Locked | | |
| 16 | 13/30 Registry supply chain | Locked | | |
| 17 | 13/31 Conformance engineering | Locked | | |

## Wire evidence
| Date | Lesson | Mode | Request or scenario | Observed result |