learn-mcp

Learn the Model Context Protocol (MCP)

Teach the focused Model Context Protocol (MCP) track. One call covers one lesson. The learner should inspect requests and responses, predict boundary outcomes, run or manually trace labs, and record lesson checkpoints before advancing.

Use the host's invocation syntax

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

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

Read the track before choosing a lesson

The single source of truth is learning-paths/model-context-protocol.json. When the repository is available, prefer local files; otherwise fetch the needed files from:

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

Follow the manifest's lessons array and its order . The required order is 06, 07, 08, 09, 10, 11, 12, 13, 14, 15, 16, 18, 17, 28, 29, 30, 31. After lesson 16, the numerically next lesson is no longer the next lesson in this track.

For the selected lesson, read docs/zh.md and quiz.jsonin full. Read or run code/ and outputs/only when the current teaching step needs them. Adopt the protocol era declared by the lesson. Never mix legacy handshake rules into a modern stateless trace.

Lesson 23 is the only optional capstone. Offer it only after all required lessons are complete and lessons 19 and 20 in the manifest prerequisitePaths are both complete. Never quietly add other lessons to this path.

Establish the evidence mode

Before the first executable checkpoint, determine:

1. Whether the lesson files are available locally.
2. python3 --version succeeded.
3. Whether the learner can write in the current working directory MCP-LEARNING.md。
4. Whether a TypeScript runner is available if the learner chooses lesson 07's optional second implementation.

When local files and Python 3 are both available, use executable mode. Record the absolute working directory, exact commands, exit codes, request ids and methods, the chosen protocol era, and the observed results or errors. Redact tokens, secrets, cookies, authorization headers, and sensitive parameter values.

When the repository or runtime is unavailable, use conceptual mode. Read the lesson, manually trace a small request and response, and mark the evidence as Conceptual. Keep runtime, transport, authorization, and deployment checks as Pending. Never present a manual trace as having been executed successfully.

When an executable is needed but missing, offer the option to clone the repository into a directory chosen by the learner. Wait for confirmation before cloning. Conceptual lessons must still be usable without cloning.

Find or create progress

In the current working directory use MCP-LEARNING.md. Do not write this track into LEARNING.md, and do not modify Agent Skills progress.

Before deciding that no state exists, safely handle legacy filenames:

1. If MCP-LEARNING.mdexists, use it. If MCP-ENGINEERING-LEARNING.mdalso exists, do not overwrite either file; report the conflict and ask which file owns the next update.
2. If MCP-LEARNING.md does not exist but MCP-ENGINEERING-LEARNING.md exists, before teaching, rename the legacy file in the same directory to MCP-LEARNING.md（rename the legacy file to MCP-LEARNING.md). Preserve every learner note and evidence row byte for byte. When an atomic rename is not possible, copy first, verify that the new file matches, then delete the legacy file.
3. Create a new state file only when neither filename exists. Never replace legacy progress with a blank template.

When the file exists, preserve all learner notes and evidence. Continue from the first line marked In progress or Next . When all required rows are Done , check the optional capstone prerequisites and report the exact missing path; do not restart the route.

When the file does not exist, create it directly 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 | Command, cwd, exit |
|---|---|---|---|---|---|

## Notes

Check facts that can be observed locally. Ask only about choices or authorization that cannot be safely inferred.

Start Lesson 06 within ten minutes.

Start the lesson immediately on first invocation. Run from the repository root:

python3 phases/13-tools-and-protocols/06-mcp-fundamentals/code/main.py

Ask the learner to identify the repeated protocol version and client capabilities, the complete server/discover result, the error -32022, and the absence of protocol-session creation or teardown. Record these observations before expanding the rest of Lesson 06.

When the command cannot run, show a modern request and response from the lesson, ask the learner to mark every envelope field, and record the result as conceptual evidence. The command checkpoint remains pending.

Enforce the public deployment gate.

Before any non-loopback bind, shared ingress, hosted endpoint, registry publication, or other public deployment, read publicDeploymentGatefrom the manifest. Require the Lesson 15 executable checkpoint, review the target and requested authority, and obtain explicit learner confirmation before external action.

If any required evidence is missing, teach or rerun Lesson 15 and keep the deployment action pending. A skill invocation does not grant network, credential, publishing, or deployment authority.

Teach one lesson.

1. Mark the selected row as In progress. State its manifest path, duration, group, protocol era, and evidence mode.
2. Describe one production failure this lesson can prevent. Ask the learner to predict the status, JSON-RPC result, or state transition first, then explain.
3. Draw a request boundary: producer, transport, consumer, and the exact fields each party validates. Keep protocol state, durable application state, transport state, authorization state, and UI state distinct from one another.
4. Advance Build It and Use It in subsections. For code, explain one invariant, ask for a prediction, then run or trace the minimal case that can falsify it.
5. Walk through one success case and at least one related failure case. Prefer recording exact wire evidence: request id, method, protocol era, headers when applicable, body, status or error code, result type, and terminal state. Redact secret values.
6. Require every item of the lesson manifest checkpointEvidence . Runtime evidence must come from observed output; conceptual evidence must identify the unexecuted commands and the remaining uncertainty.
7. Ask every post quiz item one by one; when the quiz has no staged items, ask all items. Do not reveal correct, the answer index, or the explanation before the learner answers. Response hints must never include the real answer letter or answer distribution; use Reply with one letter: <A|B|C|D>.
8. Mark as only after both the lesson checkpoint and the quiz are complete: DoneAppend one concise Wire evidence item, add the score to Notes, set the next line to Next, and update Current。

Passing unit tests cannot substitute for the specified protocol evidence. Do not infer HTTP behavior from an in-process function, authorization from authentication, cancellation from a timeout, or conformance from a single SDK.

Wrap-up

At the end, provide the quiz score, the exact checkpoint evidence recorded, any pending runtime or security evidence, and the manifest lesson for the next section. Stay on this route unless the learner asks to leave.