mcp-mastery

MCP Mastery

A self-directed, production-grade curriculum for the Model Context Protocol — built from first principles in Python, targeting the 2026-07-28 (RC) spec.

MCP Mastery is a hands-on, eight-phase journey that builds the Model Context Protocol up from a single server-and-client lifecycle to a multi-tenant, OAuth-secured, gateway-fronted deployment. Every phase is a standalone, runnable repository with its own server, hand-written client, in-memory test suite, and a complete THEORY.md — the readable companion that explains the why, not just the what.

It's a learning project written to production standards: real OAuth 2.1 against Keycloak, RFC 8693 token exchange, Redis-backed state, sandboxed execution, and a live-verified gateway.

---

The curriculum

Phase	Focus	What it builds	Status
0	Foundations & mental model	Server + hand-written client, the full lifecycle, and the stateless explicit-handle pattern	✅
1	The primitives	Tools, resources, prompts — input/output schemas, annotations, structured content, notifications	✅
2	Bidirectional primitives	Sampling (the server uses the host LLM), elicitation, roots	✅
3	Transports & the stateless rework	The same server stateful vs. explicit-handle stateless; two instances behind a load balancer; a Redis handle store	✅
4	Auth & authorization	A pure OAuth 2.1 Resource Server against Keycloak; scopes + ownership; scope step-up; RFC 8693 token exchange	✅
5	Extensions framework	MCP Apps (sandboxed HTML UI) + Tasks (long-running work); reverse-DNS negotiation; an integrated auth build	✅
6	Production hardening	A gateway doing auth propagation, per-tenant routing, rate limiting, and audit logging; Code Mode token efficiency	✅
7	Ecosystem & capstone	A multi-tenant, stateless, OAuth-secured server + a custom extension, gateway, and observability; publish to a Registry	🔜

The full curriculum map with per-phase build targets lives in mcp-phase0/docs/phases.md.

---

What it demonstrates

• Statelessness as an architecture, not a flag. The 2026-07-28 core is stateless; application state leaves the process behind explicit handles, so any request can hit any instance. Phases 3–6 cash this in repeatedly — load-balanced instances, per-user capabilities, and a gateway that needs no session affinity.
• Auth that leaves the process. The MCP server verifies, never issues. Keycloak is the real IdP; a basket_id becomes a per-user capability (scope + ownership); RFC 8693 token exchange moves delegation to where it belongs in a production topology.
• The production concerns the spec is silent on. Phase 6 engineers the gateway, multi-tenant isolation, rate limiting / cost attribution, audit trails, and code-mode token efficiency that the protocol leaves entirely to you.
• Honest engineering. Every phase names its trade-offs and the upgrades it deliberately doesn't build — the in-process store that becomes Redis, the read-modify-write race, the fixed-window limiter's burst edge, the sandbox that relies on a credential vacuum rather than a namespace jail.

---

Phase 6 spotlight — Production Hardening

The most complete phase: a plain-Starlette gateway in front of stateless MCP backends doing zero-trust auth propagation (baseline pass-through and RFC 8693 exchange that locks backends to the gateway), per-tenant routing on an IdP-asserted claim, (tenant, subject) rate limiting, and a scope-gated audit trail — plus Code Mode, a measured demonstration that tool-driven work need not pay a quadratic context bill.

118 tests (113 offline + 5 gated live) and an 8-step hand-written client walk, verified live against Keycloak + Redis in both baseline and token-exchange modes. A slide deck walks the concepts and the wire-level sequence diagrams: mcp-phase6/MCP-Phase6-Production-Hardening.pptx.

---

Repository layout

Each phase stands alone and is runnable in isolation — its own SDK pin, its own tests, its own theory:

mcp-phaseN/
  README.md             what the phase is, how to run it, the deliverable
  THEORY.md             the complete theory for the phase (a deliverable in itself)
  pyproject.toml        pins this phase's SDK version + spec target
  src/<pkg>/server.py   the phase's MCP server
  src/<pkg>/client.py   a hand-written client driving the full lifecycle
  tests/                in-memory, no-network tests (CI-friendly)

---

Running a phase

Each phase uses uv and pins the pre-release v2 SDK:

cd mcp-phaseN
uv sync --prerelease=allow                       # install (opt in to the v2 alpha)
uv run --prerelease=allow pytest                 # in-memory tests — no network, no infra
uv run --prerelease=allow src/<pkg>/server.py    # start the server (Streamable HTTP :8000)
uv run --prerelease=allow src/<pkg>/client.py    # drive it with the hand-written client

Phases 4–6 add optional live infrastructure (Keycloak + Redis); each phase's README has the exact setup, and the default test suites need none of it.

---

Spec & SDK

• Target spec: 2026-07-28 (RC) — a stateless core plus an opt-in, reverse-DNS extensions framework, distinct in load-bearing ways from the stable 2025-11-25.
• SDK: the official mcp Python SDK v2 line (2.0.0aN, alpha), pinned per phase. The installed alpha still negotiates protocol 2025-11-25 and ships the high-level server as MCPServer (there is no FastMCP in v2); each phase reconciles against the installed package and documents the gaps in its THEORY.md.

---

Secrets & configuration

All configuration is environment-driven, and no secrets are committed. Every phase ships a .env.example template; real credentials (e.g. the Keycloak token-exchange broker secret in Phases 4–6) live only in a local, git-ignored .env. The MCP servers are pure OAuth 2.1 Resource Servers — they verify tokens against Keycloak's public JWKS and hold no client secret of their own.

---

Author

Suryakant Verma — linkedin.com/in/suryakant-verma-ba573537

A personal, educational deep-dive into building MCP to production standards.