← Applied AI / Model Context Protocol (MCP)
Tutorial 07
Beginner

Model Context Protocol (MCP)

Understand the Model Context Protocol end to end — from JSON-RPC messages to a secure, multi-tenant MCP platform — explained for someone seeing it for the first time.

MCP Mastery Roadmap — Zero to Architect

A complete path to expert-level command of the Model Context Protocol (MCP), ending at the ability to design enterprise MCP architecture including authorization, entitlements, and multi-tenancy.

Current spec baseline: 2025-11-25 (the one-year anniversary release). A release candidate, 2026-07-28, is in progress and represents the largest revision since launch. This roadmap tracks 2025-11-25 and flags where 2026-07-28 changes things.

How to use this doc: it’s the spine. Each module has learning objectives, the core concepts explained inline (so reading it already teaches you), and a hands-on milestone. Work top to bottom. The four phases map to: understand → build → secure → architect.

The mental model (read this first)

MCP is a standard protocol that lets an AI application talk to external capabilities — tools, data, and prompts — without bespoke integration for each one. Think of it as “USB-C for AI applications”: one connector shape, many devices.

Three roles you must never confuse:

  • Host — the AI application the user interacts with (e.g. a chat app, an IDE, Cowork). It contains one or more clients and runs the LLM.
  • Client — a connector inside the host that maintains a 1:1 session with a single server.
  • Server — an external program that exposes capabilities (tools/resources/prompts). It does not contain the model; it just offers capabilities and responds to requests.

The single most common beginner error is thinking the server “calls the AI.” It doesn’t. The host’s model decides to call a tool; the client forwards the call; the server executes and returns a result. (The one exception — sampling — is where a server asks the client to run an LLM completion on its behalf. More on that in Module 4.)

Underneath, MCP is JSON-RPC 2.0 messages over a transport. Everything else is structure on top of that.

PHASE 1 — Foundations & Protocol (understand)

Module 1 — Why MCP exists & the architecture

Objectives: Explain the N×M integration problem MCP solves; name the three roles; describe the capability-negotiation handshake at a high level.

Core concepts:

  • The N×M problem: N AI apps each integrating M tools = N×M custom integrations. MCP turns this into N+M — every host speaks one protocol, every tool speaks one protocol.
  • Separation of concerns: hosts own the model and user; servers own capabilities and stay model-agnostic. A server you write works with any compliant host.
  • Why a protocol and not a library: language-agnostic, process-isolated, independently deployable and versioned. A Python host can use a TypeScript server.

Milestone: Write a one-page explanation, in your own words, of what happens end-to-end when a user asks a question that requires a tool call. If you can’t, re-read until you can.

Module 2 — JSON-RPC 2.0 & the message layer

Objectives: Read and hand-write the four message types; understand request IDs and error objects.

Core concepts:

  • MCP messages are JSON-RPC 2.0: requests (expect a response, carry an id), responses (result or error, same id), and notifications (no id, no response). MCP adds batching rules and uses notifications heavily for progress and list-changed events.
  • Error model: standard JSON-RPC error codes (-32600 invalid request, -32601 method not found, etc.) plus application-level errors. Crucially, a tool that fails returns a successful JSON-RPC response with isError: true in the result — protocol errors and tool-execution errors are different layers. Internalize this distinction; it matters for both UX and security.

Milestone: By hand, write the JSON-RPC for an initialize request, a tools/list request, a tools/call request, and a tool result that signals a domain error.

Module 3 — Lifecycle, capabilities & transports

Objectives: Walk through connection lifecycle; explain capability negotiation; choose the right transport.

Core concepts:

  • Lifecycle: initialize (client and server exchange protocol versions + capabilities) → initialized notification → normal operation → shutdown. Each side declares only what it supports, so features degrade gracefully.
  • Version negotiation: client proposes a protocol version (a date string like 2025-11-25); server responds with a version it supports.
  • Transports:
    • stdio — server runs as a local subprocess; messages over stdin/stdout. Simplest, no network, ideal for local/desktop tools. No network auth needed because it’s process-local.
    • Streamable HTTP — the modern remote transport (replaced the older HTTP+SSE transport). A single endpoint handles POSTed requests and can stream responses via SSE when needed. This is what you secure with OAuth (Phase 3).
    • Know the deprecation history: HTTP+SSE (two-endpoint) → Streamable HTTP. Interviewers and design reviews probe this.

Milestone: Draw the lifecycle as a sequence diagram. Annotate which messages flow over stdio vs Streamable HTTP and where a version mismatch would fail.

PHASE 2 — The Primitives & Building (build)

Module 4 — Server primitives: Tools, Resources, Prompts

Objectives: Distinguish the three server primitives by their control model; design good tool schemas.

Core concepts — the control axis is the key insight:

  • Tools — model-controlled. The LLM decides when to invoke them. Each has a name, description, and a JSON Schema inputSchema (and optionally outputSchema). Side-effecting actions live here. Good descriptions are part of the security and reliability surface — the model acts on them.
  • Resources — application-controlled. Read-only data identified by URI (e.g. file:///…, db://…). The host decides what to load into context. Think “GET, no side effects.”
  • Prompts — user-controlled. Reusable templates the user explicitly invokes (e.g. a slash command). They can take arguments and reference resources.

This model / app / user control triad is the cleanest way to remember the three. Use it in design reviews to decide where a capability belongs.

  • Tool design discipline: tight input schemas, explicit enums over free strings, clear descriptions, and outputSchema + structured content so hosts get typed results, not just text. Distinguish read vs write tools — this becomes your entitlement boundary later. Annotations like readOnlyHint / destructiveHint help hosts reason about risk.

Milestone: Design (schemas only) a server for a real domain you know — say, a ticketing system. Include at least two tools (one read, one write), one resource, one prompt. Justify each placement on the control axis.

Module 5 — Client primitives: Roots, Sampling, Elicitation

Objectives: Explain the three capabilities a server can ask of a client; understand why they invert the usual direction.

Core concepts:

  • Roots — the client tells the server which filesystem/URI boundaries it may operate within. A scoping mechanism (and a security boundary).
  • Sampling — a server requests an LLM completion from the client. This lets servers be “smart” without bundling their own model or API keys; the host stays in control of model choice, cost, and human-in-the-loop approval. In 2025-11-25, sampling can now include tool definitions (SEP-1577), enabling server-initiated agent loops.
  • Elicitation — a server asks the user (via the client) for structured input mid-operation. 2025-11-25 added URL-mode elicitation (SEP-1036): instead of collecting credentials inside the client, the server hands back a URL so the user completes a sensitive flow (OAuth, payment, API key entry) in a browser. This is important for auth UX.

Milestone: Sketch a workflow that uses all three: a server that operates only within declared roots, elicits a missing parameter from the user, and uses sampling to summarize a result.

Module 6 — Build a server (stdio) and a client

Objectives: Ship a working stdio server with tools/resources/prompts and connect it to a real host.

Core concepts:

  • Use an official SDK (TypeScript or Python are the most mature; SDKs also exist for several other languages). Don’t hand-roll JSON-RPC for your first server.
  • Implement: capability declaration, tools/list + tools/call, one resource, one prompt. Return structured content with an outputSchema.
  • Connect it to a real MCP host and to the MCP Inspector (the official debugging tool) to watch the raw protocol.

Milestone: Your server runs, appears in a host, and you can trigger every primitive. Capture the raw JSON-RPC from Inspector and read it line by line.

Module 7 — Async work & advanced UX (Tasks)

Objectives: Handle long-running operations and progress.

Core concepts:

  • Progress notifications and cancellation for long calls.
  • Tasks primitive (experimental in 2025-11-25): any request can return a task handle — “call now, fetch later.” Tasks move through working → input_required → completed / failed / cancelled. This is how MCP supports operations that outlive a single request/response and is central to robust agentic systems. Expect it to mature in 2026-07-28.

Milestone: Add a long-running tool that reports progress and can be cancelled; if your SDK supports it, expose it as a Task.

PHASE 3 — Security, Auth & Entitlements (secure)

This is the phase that turns “can build a server” into “can be trusted in production.” It’s also where most of your stated goal (entitlements + architecture) lives. Go slow here.

Module 8 — Threat model & the trust boundaries

Objectives: Enumerate where MCP can go wrong before learning the controls.

Core concepts:

  • Prompt injection via tool results / resources — untrusted content returned by a server can hijack the model. The host must treat tool output as untrusted data, not instructions.
  • Confused-deputy / token passthrough — a server must not accept a token minted for someone else and replay it upstream. Each hop validates audience.
  • Tool poisoning & rug pulls — a server can change a tool’s behavior or description after approval. Pinning, review, and provenance matter.
  • Over-broad scopes — tools that do too much, or a single token granting everything. Least privilege is the antidote (Module 11).
  • Supply chain — installing untrusted servers is running untrusted code. Sandboxing and registries matter (Phase 4).

Milestone: Write a threat model for the server you built in Module 6. For each threat, name the control you’d add.

Module 9 — The MCP Authorization spec (OAuth 2.1 foundations)

Objectives: Master the 2025-11-25 authorization model end to end. This is the heart of “entitlement and everything.”

Core concepts — learn these exact roles:

  • Authorization applies to HTTP-based transports (Streamable HTTP). stdio uses environment/OS-level trust, not OAuth.
  • The MCP server is an OAuth 2.0 Resource Server. It does not issue tokens; it validates them.
  • The MCP client is an OAuth 2.1 client, acting on behalf of the user (resource owner).
  • A separate Authorization Server (AS) issues tokens (often your IdP: Okta, Entra ID, Auth0, Keycloak, etc.).

The discovery dance (memorize this flow):

  1. Client calls the MCP server without a token → server returns 401 with a WWW-Authenticate header pointing to its Protected Resource Metadata (RFC 9728).
  2. Client fetches that metadata → finds the authorization_servers field → learns which AS to use.
  3. Client fetches the AS’s Authorization Server Metadata (RFC 8414) / OpenID Connect Discovery → learns endpoints.
  4. Client runs OAuth 2.1 Authorization Code + PKCE (PKCE is mandatory in 2025-11-25) to get an access token whose audience is the MCP server.
  5. Client calls the MCP server with Authorization: Bearer …. Server validates signature, expiry, and audience — rejecting tokens not minted for it (this defeats token passthrough).

2025-11-25 additions you must know:

  • Client ID Metadata Documents (CIMD) — the new default registration model. The client identifies itself with a URL (e.g. https://app.example.com/client.json); the AS fetches that JSON to learn the client’s metadata. Reduces reliance on pre-registration / Dynamic Client Registration.
  • OpenID Connect Discovery 1.0 support for AS discovery.
  • Authorization extensions — official hooks for environments needing custom control over the flow.
  • Enterprise / client registration management improvements for org-controlled clients.

Milestone: On paper, trace every request/response from anonymous call → 401 → discovery → token → authorized call. Label each RFC. Then put your Module 6 server behind Streamable HTTP and an AS (Keycloak or a hosted IdP) and make the real flow work.

Module 10 — Authentication vs Authorization vs Entitlements

Objectives: Separate three things people constantly conflate — the conceptual core of your goal.

Core concepts:

  • Authentication (authN) — who is the caller? Established by the validated token (identity, via the IdP).
  • Authorization (authZ) — is this caller allowed to do this action on this resource right now? This is a policy decision, and MCP deliberately leaves the policy to you — the spec gives you trustworthy identity and audience-bound tokens; the entitlement logic is yours to design.
  • Entitlements — the concrete grants: “Role Analyst in tenant Acme may call read_report but not delete_report.” Entitlements are the data; authorization is the runtime check against them.

The standard enforcement shape (PEP/PDP):

  • Policy Enforcement Point (PEP) — sits in the request path (gateway or the server itself), intercepts each tools/call.
  • Policy Decision Point (PDP) — evaluates policy (e.g. OPA/Rego, Cedar, or your IdP’s fine-grained authz) and returns allow/deny.
  • Policy Information Point (PIP) — supplies attributes (roles, tenant, resource sensitivity). This is classic XACML-style architecture applied to MCP.

Milestone: Express three entitlement rules in plain language, then in a policy language of your choice (Rego or Cedar). Decide where each is enforced (server vs gateway).

Module 11 — Designing the entitlement model (RBAC, ABAC, ReBAC)

Objectives: Choose and combine access-control models for tool-level permissions.

Core concepts:

  • RBAC — roles bundle permissions; subjects get roles. Simple, auditable, the default for tool-level grants (“which roles may call which tools”).
  • ABAC — decisions from attributes (user dept, data classification, time, environment). Use when “it depends” — e.g. allow export only for non-PII datasets during business hours.
  • ReBAC — relationship-based (Google Zanzibar / OpenFGA style): “user can read doc because they’re a member of the owning team.” Best for fine-grained, hierarchical resource graphs.
  • Scope decomposition: map OAuth scopes (coarse, set at token issuance) onto fine-grained entitlements (evaluated per call). Scopes alone are too blunt for per-tool/per-row control; you typically use scopes for coarse gating and a PDP for the fine cut.
  • The read/write split from Module 4 pays off here: destructive tools demand stricter entitlements, approval, and audit.

Milestone: Design the full entitlement model for a multi-team SaaS: roles, attributes, the resource graph, and which model governs which decision. Write the deny-by-default policy.

Module 12 — Identity propagation, multi-tenancy & isolation

Objectives: Carry verified identity and tenant context through every hop without leakage.

Core concepts:

  • Tenant context on every interaction — bind tenant to the token/session and evaluate every policy strictly within tenant boundary. Never let tenant A’s call resolve tenant B’s resources.
  • Isolation strategies — logical isolation via namespaces / server groups per business unit or environment; per-tenant RBAC; data-layer tenant scoping. Decide isolation at storage, server, and authorization layers.
  • Avoiding the confused deputy across hops — when a server needs to call an upstream API on the user’s behalf, do token exchange (RFC 8693) to get a new token with the correct audience, rather than forwarding the inbound token.
  • Auditability — log every tool/resource/prompt invocation with subject, tenant, decision, and timestamp. Audit is an entitlement requirement, not an afterthought.

Milestone: Diagram identity flowing host → gateway → server → upstream API for two tenants, showing where tokens are validated, exchanged, and where tenant isolation is enforced.

PHASE 4 — Enterprise Architecture & Mastery (architect)

Module 13 — The MCP Gateway pattern

Objectives: Design the central control plane for MCP at organizational scale.

Core concepts: A gateway is a centralized control plane that fronts many MCP servers and provides, in one place: authentication + token validation, the PEP for entitlements, RBAC/ABAC enforcement, tool-level allow/deny, rate limiting, virtual keys (per-agent/team/customer identities), tool-group bundling per role/tenant, observability, and audit. It also handles discovery/registry of servers and can do request/response inspection for prompt-injection defense. This is the backbone of enterprise MCP. Know the trade-offs: central choke point (good for control, must be HA) vs per-server enforcement (more distributed, harder to govern).

Milestone: Produce a reference architecture diagram: hosts → gateway (authN, PDP/PEP, rate limit, audit) → N servers → upstream systems, with the IdP and policy store called out.

Module 14 — Registries, distribution & supply chain

Objectives: Govern which servers exist and how they’re trusted.

Core concepts: the public/official MCP Registry and private enterprise registries; server provenance, versioning, and pinning; vetting and sandboxing third-party servers; namespacing servers to IdP groups for scoped discovery. Treat server installation as a supply-chain decision.

Milestone: Define your org’s policy for adding a server to the catalog: vetting checklist, who approves, how it’s scoped to groups, how versions are pinned.

Module 15 — Observability, reliability & scale

Objectives: Run MCP in production.

Core concepts: structured logging and audit trails with rich metadata; tracing a tool call across host→gateway→server→upstream; metrics (latency, error rate, denial rate); rate limiting and quotas per virtual key; HA for the gateway; handling Tasks/long-running ops at scale; graceful degradation when a server is down.

Milestone: Define SLOs and the dashboards/alerts for an MCP platform; describe how you’d debug a slow tool call end to end.

Module 16 — Capstone: design a secure multi-tenant MCP platform

Objectives: Demonstrate architect-level mastery in one artifact.

Deliverable — a design doc covering:

  1. Business scenario and tenants/roles.
  2. Server inventory and primitive design (tools/resources/prompts), with the read/write split.
  3. Transport choices and lifecycle.
  4. Full authorization design: RFC 9728 + 8414, OAuth 2.1 + PKCE, CIMD, audience binding, token exchange for upstream calls.
  5. Entitlement model: RBAC/ABAC/ReBAC choices, PEP/PDP/PIP placement, deny-by-default policies in Rego or Cedar.
  6. Multi-tenancy and isolation across storage/server/authz layers.
  7. Gateway, registry, observability, and audit.
  8. Threat model with mitigations mapped to controls.

If you can write and defend this document, you are operating at the level you set out to reach.

Cross-cutting practices (do these the whole way through)

  • Read the spec, not just blogs. modelcontextprotocol.io/specification/2025-11-25. Re-read the authorization section until the RFC flow is automatic.
  • Use the Inspector to see raw protocol on everything you build.
  • Keep a glossary (host, client, server, AS, RS, PEP/PDP/PIP, CIMD, PKCE, RFC 9728/8414/8693, RBAC/ABAC/ReBAC, scopes vs entitlements).
  • Track 2026-07-28 as it lands — it hardens authorization and is the biggest revision since launch.

Suggested pace

  • Weeks 1–2: Phase 1 (Modules 1–3) + start Module 4.
  • Weeks 3–4: Phase 2 (Modules 4–7) — build something real.
  • Weeks 5–7: Phase 3 (Modules 8–12) — the auth/entitlement core; slowest, most valuable.
  • Weeks 8–10: Phase 4 (Modules 13–16) — architecture + capstone.

Adjust to your time; the ordering matters more than the calendar.

Primary sources

Start: Module 01 — Why MCP Exists & The Architecture →
← Previous tutorial
Next tutorial →