Skip to content
All learning paths

Study notes · six weeks · 3–4 h a week

MCP Learning Path

A course I put together for learning the Model Context Protocol, from concepts to shipping and contributing to an MCP server. It sequences three resources against the current 2026-07-28 spec.

The core material

ResourceRoleUse it for
Official MCP docsSource of truthConcepts, the current spec (2026-07-28), SDKs, security, Inspector
Hugging Face MCP CourseGuided hands-onUnits 1–3 with quizzes, projects and two free certificates
Mastering MCP (Educative)Subscription courseAbout 7 h on multi-server MCP, RAG servers, authorization and debugging
Flow FrameworkReal-world codebaseHow a production framework exposes tools as an MCP server, CLI and plugin

01 / Week 1

Fundamentals and architecture

Explain hosts, clients and servers, the three server primitives, and how JSON-RPC messages flow between them.

Read (official docs, ~1.5 h)

  1. What is MCP?: the USB-C-for-AI framing and who supports it
  2. Architecture overview: host, client, server; data layer vs transport layer
  3. Understanding MCP servers: tools (model-controlled), resources (app-controlled), prompts (user-controlled)
  4. Understanding MCP clients: elicitation and what clients offer back
  5. Versioning: date-based versions, and why they matter for SDK choice

Do (HF Unit 1, ~2 h)

Optional (Educative, ~2 h)

Lab: Open the MCP Inspector against any example server. List tools, call one, read a resource, and watch the raw JSON-RPC traffic.

CheckpointExplain in two minutes the M×N integration problem and why tools, resources and prompts have different controllers.

02 / Week 2

Build your first server and client

Ship a working stdio server with the current SDK, connect it to a host, then write a client that drives it.

Build the server (~2 h)

  • Build an MCP server: a weather server with get_alerts and get_forecast
  • Python SDK 2.0.0+ uses the MCPServer class; older tutorials, including the HF course, use FastMCP. Same idea, older API.
  • Try the C# tab too: ModelContextProtocol on NuGet with [McpServerTool] attributes. C# is a Tier 1 SDK.
  • The rule that bites everyone: on stdio, never write to stdout. Log to stderr.
  • Any MCP host works for testing, including VS Code.

Build the client (~1.5 h)

Verify against both protocol eras

  • Run the Inspector CLI once with --protocol-era modern and once with --protocol-era legacy; both must list your tools.
  • Inspector CLI
  • Protocol eras

Stretch: Add one resource (a static config file) and one prompt (a reusable “summarize alerts” template), so you have used all three primitives.

CheckpointYour server passes tools/list in both eras and you can read the JSON-RPC for one tools/call round trip.

03 / Week 3

End-to-end MCP application

Build and deploy a sentiment-analysis MCP server with Gradio, then reach it from two different clients.

Do (HF Unit 2, ~3 h)

  1. Unit 2 introduction: Python 3.10+, Node 18+ and a free HF account
  2. Gradio server: mcp_server=True turns a typed Python function into an MCP tool; deploy it to a free HF Space
  3. Gradio as a client: a smolagents MCPClient wrapped in a UI
  4. Tiny Agents: a JSON-configured agent in JS or Python that uses your deployed server

Watch for: The course connects over /gradio_api/mcp/sse and bridges with mcp-remote. HTTP+SSE is now a deprecated transport; finish the unit and revisit it in week 5.

Why it's worth it: Seeing one server serve two unrelated clients is the core MCP promise made concrete, and HF Spaces host it for free.

CheckpointYour Space URL works from both a Tiny Agent and the Inspector. Units 2 and 3 together earn the HF certificate of completion.

04 / Week 4

Advanced workflow servers

Build a PR-workflow server that uses tools, resources and prompts together, then a webhook-driven agent that acts on its own.

Unit 3: custom workflow servers (~3 h)

  1. Unit 3 introduction: tools that pick the right PR template from changed files
  2. GitHub Actions integration: a webhook receiver, CI-status tools and four MCP prompts
  3. Team notifications (Slack) that combine all three primitives.
  4. Solution walkthrough

Unit 3.1: PR agent on the Hub (~2 h)

The pattern: An HTTP service receives an event, an agent calls MCP tools, a side effect lands. The same shape works with any event source.

Do the exercises: The custom workflow prompt and event filtering exercises are where prompts click.

CheckpointExplain when you would make something a prompt rather than a tool, with one example from your own server.

05 / Week 5

Production MCP: current spec, transports, auth, security

Close the gap between what the HF course teaches and the 2026-07-28 spec, then cover what a remote server needs in front of real users.

TopicWhat the HF course showsCurrent spec (2026-07-28)
Handshakeinitialize, then initializedStateless: version and client capabilities ride in each request's _meta; servers must implement server/discover
SessionsMcp-Session-Id headerRemoved; cross-call state uses server-minted handles passed as tool arguments
Remote transportHTTP+SSE (/mcp/sse)Streamable HTTP; HTTP+SSE is deprecated
Server asking the clientsampling, elicitation and roots requestsMulti Round-Trip Requests: server returns input_required, client retries with answers
Change notificationsGET stream, resources/subscribeOne subscriptions/listen POST stream
Roots, Sampling, LoggingCore featuresDeprecated (SEP-2577): use tool params, direct LLM calls, stderr or OpenTelemetry
Long-running workExperimental tasks in coreio.modelcontextprotocol/tasks extension with polling
ResultsNo type tagRequired resultType, plus ttlMs and cacheScope on list results

Source: 2026-07-28 changelog

Read (~3 h)

Lab: Port your week-3 server to Streamable HTTP with the current SDK, put it behind OAuth, and pass the Inspector in the modern era.

CheckpointExplain why removing sessions makes MCP servers easier to scale behind a load balancer.

06 / Week 6

MCP inside Flow Framework

Flow turns the same zod-typed tools written for a chat agent into an MCP server, a CLI and native plugins. Trace that path and find a first contribution.

MCP conceptHow Flow does itWhere to look
Server + transportmcpServer({ name, version, tools, dir }) serves Streamable HTTP at /mcp on the official SDKmcp/src
Tool metadatatitle, output, status and hints become MCP annotations (readOnly, destructive, idempotent, openWorld)mcp/src
InstructionsAgent skills ship as server instructions plus a read_skill toolmcp/src, coding-agents/
AuthorizationHost OAuth against your own issuer; signIn per tool; 401 triggers the host's sign-incoding-agents/auth-skill.md
Consuming serversmcpTools({ name, url }) imports another server's tools, pinned in mcp.lock.jsonmcp/src
CLI over MCPStricli CLI where every tool is a command with --json, --dry-run, --yescli/src
Pluginsflow plugin emits Claude Code and Agent Plugins 1.0.0 packagesREADME
Observabilitytool.start / tool.end events and OTLP traces per tool callREADME

Source: Flow README

Lab (~3 h)

  1. Read AGENTS.md first: then npm ci, npm run new -- my-agent, npm start
  2. Expose the café example's tools with mcpServer and connect the Inspector in both protocol eras.
  3. Point any MCP host at it and call get_menu.
  4. Generate the CLI with npx flow cli --server <url> -h and run npx flow check.
  5. Follow one tool from its tool({...}) definition to the tools/list JSON the Inspector shows.

Contribution hunt

  • Does the server answer server/discover and return resultType and ttlMs/cacheScope per 2026-07-28, or only the legacy handshake?
  • Are tools/list results in deterministic order, as the spec now recommends for client caching?
  • Do the mcp/ tests cover both protocol eras?

CheckpointA draft issue or PR on Flow's mcp/ or cli/ package, grounded in a spec section you can cite.

Capstone

Build one remote MCP server that uses all three primitives, runs on the current spec, and is published somewhere real, such as a free HF Space listed in the MCP Registry. Done when every line holds:

Reference links