MCP Tutorial with Examples.
MCP tutorial: build Model Context Protocol servers and clients in Python, with tools, resources, prompts, the wire protocol, HTTP and security.
Architecture at a glance
Click any box to open the lesson that teaches it
MCP architecture at a glance
host + LLM → MCP client ↔ JSON-RPC ↔ MCP server → tools, resources, prompts
How it fits together (8 steps)
- The host app's LLM decides to call a tool, running the tool-use loop — or, across many steps, an agent loop.
- It talks through an MCP client, which discovers what a server offers before any call is made.
- Requests and responses travel as JSON-RPC over stdio or Streamable HTTP; the same server also runs over HTTP, testable with the Inspector.
- The MCP server exposes tools, resources and prompts with argument completion.
- Mid-call, the server can ask the client for things: sampling the client's model, reading roots, or eliciting a missing argument from the user, while logging, progress and cancellation ride the same connection.
- The result comes back structured and schema-checked, via
outputSchemaandstructuredContent, and the loop decides whether to call another tool or stop. - Shipping it needs auth and security: OAuth fundamentals wired into OAuth 2.1 and CIMD, server-side security, and LLM security beyond guardrails.
- In production: OpenTelemetry traces follow a call across client and server, and scaling, caching and operational controls keep it running.
Beginner
Start here — no prior experience needed
MCP Learning Roadmap
A Model Context Protocol roadmap: first server and client, the wire protocol, client features and testing, OAuth and security, then production and tracing.
MCP: Your First Server and Client
Build a Model Context Protocol server with one tool in Python, call it from a scripted client over stdio and in memory, and see why stdout is off limits.
MCP Tools: Schemas, Results and Errors
See the inputSchema MCP builds from Python type hints, return structured output, and tell tool errors from protocol errors, all with real printed results.
MCP Resources and URI Templates
Expose data as MCP resources: static URIs, {name} templates, MIME types and base64 blobs, plus what a client gets for a missing URI, all with real output.
Intermediate
For developers with core concepts down
MCP Prompts and Argument Completion
Write MCP prompt templates with required and optional arguments, return multi-message prompts, and suggest argument values with completion/complete.
The MCP Wire Protocol: JSON-RPC by Hand
Talk to an MCP server with raw JSON lines: the 2026-07-28 _meta envelope, resultType, server/discover, error codes -32602 and -32022, and legacy clients.
Logging, Progress and Cancellation in MCP
Report progress from a long MCP tool, cancel or time out a call and see the server clean up, and opt in to protocol logging, deprecated as of 2026-07-28.
MCP Observability with OpenTelemetry Traces
Trace an MCP server with OpenTelemetry: the spans the Python SDK emits by default, failing tools, one trace across client and server, and export to Jaeger.
Advanced
Production-grade patterns for experienced engineers
Elicitation, Sampling and Roots (Multi Round-Trip Requests)
Let an MCP server ask the client for input mid-call: elicitation, sampling and roots via multi round-trip requests, with scripted callbacks.
Streamable HTTP, Testing and the MCP Inspector
Serve MCP over Streamable HTTP, call it from Client and curl with the required headers, test it in memory with pytest, and drive it with the Inspector.
MCP Server Security
Defend MCP servers and hosts: contain file paths, keep resource checks on, audit and pin tool descriptions, distrust annotations, and guard credentials.
MCP Authorization: OAuth 2.1, CIMD and a Real Identity Provider
Protect an MCP server with OAuth: the 401 and resource metadata, audience and scope checks, CIMD versus DCR, token refresh, Keycloak and DPoP in the SDK.
Running MCP in Production: Scaling, Caching and Operations
Run MCP as several instances: nginx and the 421 Host check, a shared request-state key, SQLite, cache hints, key rotation, audit logs and Kubernetes.
Also part of MCP (Model Context Protocol)
Taught in other topics. Each link opens the lesson in its home topic.
LLM Tool Use and Function Calling
Tool schemas, argument validation, the tool_use/tool_result loop, error recovery, parallel calls and approval gates, all run against a scripted model.
Structured Outputs in Production
Why 'return JSON only' isn't enough, and how schema validation plus a retry loop turns a flaky text model into a reliable data source.
LLM Security Beyond Guardrails
Indirect prompt injection, excessive agency, and insecure output handling — the OWASP-style risks that survive input/output guardrails.
An Agent Loop Over MCP Tools, With Human Approval
Build an agent loop on MCP: discover tools, validate a plan, run read-only tools freely, gate destructive ones on approval, and use several MCP servers.
OAuth and Token-Based Authorization
OAuth from first principles in runnable Python: the three roles, scopes and audiences, short access tokens, rotated refresh tokens, PKCE and DPoP binding.