MCP Crash Course
All of the Model Context Protocol on one page — architecture, primitives, transports, auth, and what changed in the 2026-07-28 spec
MCP Crash Course
Start here
This single page covers all of MCP (Model Context Protocol) at working depth. Read it start to finish in about 30 minutes and you will understand the architecture, every primitive, how transport and authorization actually work, and — critically — what changed in the current spec, since a lot of what circulates online about MCP is now out of date.
Every section ends with a Go deeper link to a full page on that topic. Read this first, then follow the links for whatever you need in detail.
| Property | Value |
|---|---|
| Level | Everyone — starts from zero, ends at production |
| Reading time | ~30 minutes |
| Prerequisites | None. The AI Agents crash course helps for context on tool use, but isn't required. |
| You will understand | The whole MCP protocol, current as of spec version 2026-07-28, well enough to build and connect servers |
1. What MCP Is
The one-sentence definition
MCP is an open protocol that standardizes how AI applications connect to external tools, data, and workflows — the same way USB-C standardized how devices connect to peripherals, instead of every combination needing its own cable.
Before MCP, every AI application that wanted to use, say, GitHub, Slack, and a local filesystem had to write three separate, bespoke integrations. Every other AI application wanting the same three integrations had to write them again. That's an M × N problem — M applications, N tools, M×N integrations.
MCP turns it into M + N: each tool is exposed once, as an MCP server; each application implements MCP once, as an MCP host. Any host can then talk to any server.
| Term | Role |
|---|---|
| Host | The AI application — Claude Desktop, Claude Code, VS Code, Cursor |
| Client | A connector inside the host, one per server, holding the dedicated connection |
| Server | A program exposing tools, data, or workflows through the protocol |
MCP has two layers: a data layer (JSON-RPC 2.0 messages defining tools, resources, prompts, and notifications) and a transport layer (how those messages actually travel — stdio for local processes, Streamable HTTP for remote servers).
MCP does not dictate how an application uses an LLM. It standardizes context exchange — getting tools and data into an AI application — not the model, the prompt, or the agent loop around it. Those are the host's business.
Go deeper: What Is MCP?.
2. The Architecture, in Practice
This changed recently — read this even if you already know MCP
As of protocol version 2026-07-28, MCP is stateless. The old model — a single initialize handshake at the start of a session — is gone. Every request now carries its own protocol version, capabilities, and identity in a _meta field, so a server can process any request without relying on prior connection state.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "weather_current",
"arguments": { "location": "San Francisco" },
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": { "name": "example-client", "version": "1.0.0" },
"io.modelcontextprotocol/clientCapabilities": { "elicitation": {} }
}
}
}A client that wants to know what a server supports before doing anything else can send an optional server/discover request — it returns supported versions, capabilities, and a caching hint (ttlMs, cacheScope), so the discovery result can be reused instead of re-fetched on every call.
Go deeper: The MCP Architecture.
3. Tools
Tools are functions the model decides to call — search flights, send a message, query a database.
{
name: "searchFlights",
description: "Search for available flights",
inputSchema: {
type: "object",
properties: {
origin: { type: "string", description: "Departure city" },
destination: { type: "string", description: "Arrival city" },
date: { type: "string", format: "date" }
},
required: ["origin", "destination", "date"]
}
}Protocol operations: tools/list to discover, tools/call to execute. Tools may require explicit user consent before they run — the same "the model requests, the application decides" boundary covered in the Agents track.
Tool descriptions and annotations from an untrusted server should be treated as untrusted input, not documentation. A malicious or compromised server can write a description designed to manipulate the model — this is MCP's version of prompt injection, and it's a named concern in the spec's own security principles.
Go deeper: Tools.
4. Resources and Prompts
Resources and prompts are the other two things a server can expose, and they're controlled by different parties.
| Primitive | Controlled by | Purpose |
|---|---|---|
| Tools | The model | Take an action |
| Resources | The application | Read-only context — files, schemas, records |
| Prompts | The user | Reusable, parameterized templates — slash commands |
Resources come as direct resources (a fixed URI, e.g. calendar://events/2026) or resource templates (a parameterized URI, e.g. weather://forecast/{city}/{date}), and support parameter completion — typing "Par" suggests "Paris." Prompts work similarly, surfaced as things like /plan-vacation with typed arguments.
Go deeper: Resources & Prompts.
5. What Got Deprecated
If you learned MCP before mid-2026, this is the section to read
Three client-side primitives were deprecated in spec version 2026-07-28. A lot of tutorials, blog posts, and even some SDK examples still teach these as current — they aren't anymore.
| Primitive | Was for | Migration |
|---|---|---|
| Sampling | Server asks the client's LLM to run a completion, so the server stays model-independent | Integrate directly with an LLM provider API instead |
| Roots | Client tells a server which directories/files are "in scope" | Pass paths via tool parameters, resource URIs, or server configuration |
| Logging (as a protocol primitive) | Server sends log messages to the client | Log to stderr (stdio transport) or use OpenTelemetry |
None of these are removed outright — under MCP's feature lifecycle policy they stay in the spec for at least twelve months after deprecation — but new implementations should not adopt them, and existing ones should migrate.
Go deeper: Deprecated Primitives.
6. Elicitation
The one client-side primitive that's still fully current: elicitation lets a server ask the user for more information mid-operation — confirming a destructive action, or filling in a missing parameter — via elicitation/create.
Server: "About to delete 47 files matching *.tmp — confirm?"
Client: shows the prompt to the user, returns their answer
Server: proceeds, or stops, based on the responseGo deeper: Elicitation.
7. Transports
Two transports, two shapes of server
stdio — local
RecommendedStandard input/output between processes on the same machine. No network overhead, typically serves exactly one client. This is how Claude Desktop runs a local filesystem server.
Streamable HTTP — remote
HTTP POST for client-to-server messages, with optional Server-Sent Events for streaming. Serves many clients at once, supports standard HTTP auth (bearer tokens, OAuth). This is how a hosted server like Sentry's MCP server works.
The older, standalone "SSE transport" from early MCP is gone — Server-Sent Events are now just an optional streaming mode within Streamable HTTP, not a separate transport to choose between.
Go deeper: Transports.
8. Authorization and Security
Authorization is optional in MCP, but when a server needs it — any remote, HTTP-based server handling real data usually does — it's built on OAuth 2.1, with the MCP server acting as an OAuth resource server.
The authorization flow, compressed
Three core security principles, regardless of transport: users must explicitly consent to data access and tool execution; hosts must never transmit resource data elsewhere without consent; and tool behavior descriptions from an untrusted server should never be taken at face value. MCP enables arbitrary data access and code execution paths — treat it with the caution that implies.
Go deeper: Authorization & Security — the full OAuth flow, step-up authorization, and the confused-deputy threat model.
9. Building a Server (and a Client)
A minimal Python MCP server, using the official SDK's high-level FastMCP interface:
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("weather")
@mcp.tool()
async def get_forecast(city: str) -> str:
"""Get the weather forecast for a city."""
return f"Sunny, 22°C in {city}"
if __name__ == "__main__":
mcp.run(transport="stdio")The decorator handles JSON Schema generation from the function signature and docstring — you write a typed Python function, the SDK produces the tools/list entry. Test it locally with the MCP Inspector before wiring it into a real host.
Go deeper: Building Servers & Clients.
10. Connecting Claude to MCP
Three distinct ways to bring MCP into Claude, for three different situations:
| Surface | Use when |
|---|---|
Claude Code (claude mcp add) | You're coding, and want tools available in your terminal agent |
| Claude Desktop (config file) | You want tools available in the consumer chat app |
| Claude API — MCP connector | Your own application should talk to a remote MCP server directly from a Messages API call |
# Claude Code — remote server over HTTP, with an auth header
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer YOUR_GITHUB_PAT"
# Local stdio server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-server# Claude API — the MCP connector needs both halves
response = client.beta.messages.create(
model="claude-opus-5",
max_tokens=4096,
betas=["mcp-client-2025-11-20"],
mcp_servers=[{"type": "url", "url": "https://mcp.example.com", "name": "example"}],
tools=[{"type": "mcp_toolset", "mcp_server_name": "example"}],
messages=[{"role": "user", "content": "..."}],
)The MCP connector needs both halves. Declaring mcp_servers alone is rejected — you must also declare the matching mcp_toolset tool with the same mcp_server_name.
Go deeper: Connecting Claude to MCP — full claude mcp add reference, scopes, OAuth, and headers.
11. Extensions
Beyond the core protocol, MCP defines optional, opt-in extensions — always negotiated during discovery, never assumed.
| Extension | What it adds |
|---|---|
| Tasks | Durable handles for long-running operations — poll for status, accept mid-flight input |
| MCP Apps | Interactive UI rendered inline in the conversation — charts, forms, a video player |
| Skills over MCP | Rich, structured agent-workflow instructions discovered through MCP |
| Auth extensions | OAuth client-credentials flow for machine-to-machine access, enterprise-managed authorization |
Go deeper: Extensions.
12. MCP in Agent Systems
An MCP server is, from an agent's point of view, just a source of tools — everything the Agents track teaches about tool design applies directly: keep the tool list short, write descriptions that say when not to use a tool, use enums over free text.
Connecting five MCP servers can mean fifty tools arriving in one shot. Past roughly 15 tools, model tool-selection quality measurably drops — the same ceiling covered in the Agents track. Progressive tool discovery (loading tool definitions on demand instead of all upfront) is the standard mitigation once you're federating more than a couple of servers.
Go deeper: MCP Agents & Tool Design.
13. Production Essentials
| Area | The thing you must get right |
|---|---|
| Treat every server as untrusted by default | Especially third-party ones — validate tool descriptions, cap output size, sandbox execution |
| Cap tool output size | Claude Code defaults to 25,000 tokens per tool call — an unbounded response can blow a context budget silently |
| Handle reconnection deliberately | Remote servers reconnect with backoff; stdio servers generally don't — design for both |
| Version your own servers | Advertise supported protocol versions honestly; breaking changes need a real migration path |
| Log for debugging, not the deprecated way | stderr or OpenTelemetry, not the removed logging primitive |
| Scope credentials narrowly | Least-privilege OAuth scopes, step-up authorization for anything higher-risk |
Go deeper: Production & Operations.
14. When It Breaks
| Symptom | Usual cause |
|---|---|
| Server's tools never show up | Missing or malformed tools/list response, or a server/discover capability mismatch |
| Tool call rejected with a schema error | inputSchema doesn't match what the model actually sent — tighten or loosen the schema |
| Auth loop that never completes | Missing resource parameter (RFC 8707), or a client using a token issued for a different server |
| Notifications never arrive | Client never opened a subscriptions/listen stream, or asked for a filter the server didn't acknowledge |
| A tool call takes down the whole context | Output size uncapped — a single call returned megabytes of text |
| Works locally, fails when hosted remotely | stdio-specific assumption (single client, no auth) carried into a Streamable HTTP deployment |
Go deeper: Failure Modes & Debugging.
15. Vocabulary You Need
| Term | Meaning |
|---|---|
| Host | The AI application coordinating one or more MCP clients |
| Client | The connector inside a host, one per server |
| Server | A program exposing tools, resources, or prompts via MCP |
| Data layer | The JSON-RPC 2.0 message protocol — tools, resources, prompts, notifications |
| Transport layer | How messages actually travel — stdio or Streamable HTTP |
server/discover | The optional, cacheable request a client sends to learn a server's capabilities |
| Tool | A model-controlled, invokable function |
| Resource | Application-controlled, read-only context |
| Prompt | A user-controlled, reusable template |
| Elicitation | A server asking the user for more input mid-operation |
| Sampling, Roots, Logging | Deprecated (2026-07-28) client-side primitives |
| Extension | An optional, opt-in protocol addition, negotiated during discovery |
| Protected Resource Metadata | RFC 9728 — how an MCP server advertises its authorization server |
| Confused deputy | A tricked, trusted party (the model) performing an unintended, higher-privilege action |
Go deeper: Glossary.
16. The Rules
| # | Rule |
|---|---|
| 1 | MCP standardizes context exchange, not the agent loop. The host decides how to use what MCP gives it. |
| 2 | The protocol is stateless as of 2026-07-28. Every request carries its own version and capabilities — there's no session handshake to rely on. |
| 3 | Sampling, Roots, and Logging are deprecated. Don't build new integrations on them. |
| 4 | Tools are model-controlled; resources are application-controlled; prompts are user-controlled. Design each accordingly. |
| 5 | Treat tool descriptions from untrusted servers as untrusted input, not documentation. |
| 6 | stdio for local, Streamable HTTP for remote. There's no separate SSE transport anymore. |
| 7 | Authorization is OAuth 2.1, scoped to one server per token. A token for one MCP server must never be sent to another. |
| 8 | Cap tool output size. An unbounded response is a silent context-budget killer. |
| 9 | Extensions are always opt-in and negotiated. Never assume one is supported without checking. |
| 10 | More servers means more tools arriving at once. Past ~15 tools, selection quality drops — same ceiling as any agent's tool list. |
| 11 | Consent before access, every time. The spec's core security principle, not a suggestion. |
| 12 | Version your own servers honestly. A silent breaking change is worse than a slow migration. |
17. Where To Go Next
The protocol, in order
| Page | Covers |
|---|---|
| What Is MCP? | The M×N problem, host/client/server, the two layers |
| The MCP Architecture | The stateless model, _meta, server/discover, caching |
| Tools | Schemas, consent, untrusted-description risk |
| Resources & Prompts | Direct resources, templates, parameter completion, slash commands |
| Deprecated Primitives | Sampling, Roots, Logging — what they were and their migrations |
| Elicitation | The remaining client primitive, and the MRTR pattern |
| Transports | stdio vs Streamable HTTP in depth |
| Authorization & Security | OAuth 2.1, step-up auth, the confused-deputy threat model |
Building and connecting
| Page | Covers |
|---|---|
| Building Servers & Clients | The Python SDK, FastMCP, the MCP Inspector |
| Connecting Claude to MCP | claude mcp add, Claude Desktop, the API's MCP connector |
| Extensions | Tasks, MCP Apps, Skills over MCP, auth extensions |
| MCP Agents & Tool Design | Tool surface design, progressive discovery, tying into the Agents track |
Running it for real
| Page | Covers |
|---|---|
| Production & Operations | Trust boundaries, output limits, reconnection, versioning |
| Failure Modes & Debugging | Symptom to cause, across every stage |
| Designing an MCP-Based System | A full worked design with real numbers |
| Glossary | Every term and abbreviation |
Then build something
Reading takes you only so far. Project Ideas lays out one modern project that puts a real MCP server — resources, tools, and remote auth — in your own hands.
Support Operations Agent
Build an agent that resolves support tickets by taking real actions, with a policy gate, idempotent writes, and a loop that pauses for human approval
What Is MCP?
The M×N integration problem MCP solves, the host/client/server model, and what the protocol does and doesn't standardize