The Model Context Protocol,
explained the way agents actually use it.

What's new in 2026-07-28

The largest breaking change since MCP launched. MCP is now a stateless request/response protocol. If you last read about MCP before August 2026, read this section first - several things you learned are no longer true.

Also in this release

• Extensions framework (SEP-2133) - reverse-DNS identified, independently versioned, always opt-in. Tasks, MCP Apps, Skills over MCP and the auth extensions all live here.
• Tasks left the core (SEP-2663) - now io.modelcontextprotocol/tasks, with polling via tasks/get and a new tasks/update for mid-flight input.
• subscriptions/listen replaces the HTTP GET endpoint and resources/subscribe, with per-type client opt-in.
• Authorization hardening - RFC 9207 iss validation, issuer-bound client credentials, application_type in DCR, and Client ID Metadata Documents as the preferred registration path.
• Full JSON Schema 2020-12 in inputSchema and outputSchema, including oneOf, anyOf, allOf and $ref.
• A formal deprecation policy - Active → Deprecated → Removed, with a twelve-month minimum window.
• No SSE resumability - Last-Event-ID and event IDs are gone. A broken stream means the client re-issues the request, so make side-effecting tools idempotent.

What is MCP?

An open JSON-RPC 2.0 standard that gives any LLM a single, uniform way to call tools, read data, and use reusable prompts from any compliant external system. The "USB-C for AI" - one connector, every device.

A short history

• Nov 2024 - Anthropic publishes the spec (2024-11-05) and open-sources the SDKs.
• 2025 - OpenAI, Google DeepMind, Microsoft, AWS and most major IDEs adopt MCP. Revisions 2025-03-26 (Streamable HTTP, OAuth) and 2025-06-18 (elicitation, structured output) land.
• Nov 2025 - 2025-11-25 ships: experimental tasks, URL-mode elicitation, further authorization work.
• Dec 2025 - Anthropic donates MCP to the Agentic AI Foundation under the Linux Foundation, reinforcing vendor-neutral governance.
• Mar 2026 - The 2026 roadmap names transport scalability, agent communication, governance and enterprise readiness as priorities. The extensions framework arrives.
• Jun 2026 - Enterprise-Managed Authorization reaches stable, adopted by Anthropic, Microsoft and Okta.
• 28 Jul 2026 - 2026-07-28 ships the stateless core, MRTR, header routing, cacheable lists, auth hardening and extensions. All four Tier 1 SDKs (TypeScript, Python, Go, C#) speak it on day one; Rust follows in beta.
• Aug 2026 - A new roadmap sets five priority areas for the next cycle.

At the 2026-07-28 release the maintainers reported close to half a billion downloads a month across the Tier 1 SDKs, with the TypeScript and Python SDKs each crossing 1 billion total downloads.

Protocol revisions at a glance

The spec calls 2025-11-25 and earlier legacy (they establish a session with an initialize handshake) and 2026-07-28 and later modern (version, identity and capabilities travel as per-request metadata). An implementation supporting both is dual-era.

The building blocks

MCP organizes capabilities into a small set of named primitives. Three live on the server, three used to live on the client (two are now deprecated), and a handful are protocol-level. Know them cold.

Server-side primitives what your server exposes

Client-side primitives what the server can ask the host to do

Protocol-level primitives

• Per-request metadata (_meta) - replaces the handshake. Every request carries io.modelcontextprotocol/protocolVersion and clientCapabilities (both required); clients should add clientInfo, and servers should return serverInfo in each result.
• server/discover - mandatory RPC advertising supported versions, capabilities, identity and instructions. Optional for clients to call.
• subscriptions/listen - one long-lived stream for opted-in change notifications: toolsListChanged, promptsListChanged, resourcesListChanged, resourceSubscriptions. Servers must not push types the client didn't request.
• Caching hints - ttlMs and cacheScope (public / private) are required on list and read results. MRTR retries must never be cached.
• Result types - every result carries resultType: "complete" or "input_required". A missing field from a legacy server means "complete".
• Capability negotiation - per request, plus an extensions map on both client and server capabilities for opt-in features.
• Tracing - W3C Trace Context keys (traceparent, tracestate, baggage) are documented _meta conventions, so a tool call joins your distributed trace.
• Logging deprecated - level is now set per request via io.modelcontextprotocol/logLevel; logging/setLevel is removed. Use stderr on stdio, or OpenTelemetry.

How MCP works, end-to-end

Built on JSON-RPC 2.0. Every message is a request, response, or notification - and since 2026-07-28, every request is self-describing. Two standardized transports: stdio for local, Streamable HTTP for remote.

There is no session, and no handshake

This is the defining change of 2026-07-28. No initialize exchange, no Mcp-Session-Id header, no per-connection list results, no SSE resumability, no ping. The practical consequence: any request can land on any instance behind a plain round-robin load balancer - no sticky routing, no shared session store, no drained sessions on redeploy. A server that genuinely needs cross-call state mints an explicit handle and hands it back as an ordinary tool argument.

Multi Round-Trip Requests (MRTR)

Server-initiated requests needed an open, sticky stream, so they couldn't survive a stateless core. MRTR inverts them. When a server needs an elicitation, a sampling completion or a roots list, it does not call the client - it returns an interim result:

Header-based routing

Streamable HTTP POSTs must now carry standard headers so gateways, rate limiters and WAFs can route and meter without parsing the body. A mismatch between a header and the body is a HeaderMismatch error (-32020).

Tools may additionally promote individual parameters into HTTP headers with an x-mcp-header annotation in the input schema - useful for routing on a tenant or region without cracking the payload open.

Error codes

The two transports, side by side

What to consider when building a server

A "hello world" MCP server is 50 lines. A production-grade one is a product. Here's the checklist that separates toys from tools agents love.

1. Define the agent story first. Write the user-and-agent workflows you want to support, then design the minimum tools to satisfy them in one or two calls - not seven.
2. Pick the right transport. stdio for local; Streamable HTTP for remote multi-tenant.
3. Design for statelessness - it's now the protocol's default. Not a deployment preference any more. Every handler must be independently servable by any instance; mint explicit handles for anything spanning calls.
4. Budget your tool surface. 5-8 tools per server is the sweet spot. Past ~12, agent performance degrades.
5. Write tool descriptions for the LLM. Action-first, disambiguating, under ~200 tokens. They go straight into the context window.
6. Design payloads for context economy. Return only what the agent needs for the next decision. Offer a verbose flag if power users need more.
7. Set caching hints honestly. A generous ttlMs on a stable catalog saves a round trip every turn. The same on a per-user tool list is a correctness bug - and cacheScope: "public" on anything user-specific is a data-leak bug. When in doubt: private, short TTL.
8. Errors are guidance, not just failures. "Permission denied" is bad. "Reauthenticate with repo:write scope" is useful. Use the allocated code ranges; never invent codes in -32020..-32099.
9. Version gracefully. Tool names and schemas are a public API. Add fields as optional; never repurpose existing ones. Return a deterministic tool order so client and prompt caches stay warm.
10. Plan your dual-era story. You'll serve legacy and modern callers together for a while. Let server/discover and UnsupportedProtocolVersionError do the negotiating.
11. Observability from day one. Structured logs, per-tool latency, audit trail of who called what. Propagate traceparent from _meta.

Why MCP and not just APIs?

MCP and REST solve different problems for different consumers. The fastest way to misuse MCP is to think of it as "an API with extra steps." It isn't.

Note how much of that table converged on REST in 2026-07-28. That's the point: a remote MCP server is now, operationally, just another HTTP workload. What still distinguishes MCP is who the consumer is and how the contract is described.

When to reach for each

How agents interact with MCP

From the agent's point of view, MCP tools look identical to natively defined functions - but richer, with semantic descriptions and live discovery.

The five phases of agent ↔ MCP

1. Connection - host spawns or connects each configured server. There's no handshake to run; it may call server/discover to pin a version and read capabilities.
2. Discovery - client calls tools/list; descriptions land in the agent's system prompt. Because results carry ttlMs, a well-behaved host caches them rather than re-listing every turn.
3. Decision - LLM, given the catalog, decides whether to answer or call a tool. MCP's richer descriptions improve tool-selection accuracy materially.
4. Invocation - chosen call goes out as tools/call with _meta and the routing headers; server executes; result feeds back as a tool message.
5. Mid-flight input & notifications - long tools stream notifications/progress on their own response. If the server needs input it returns input_required and the client retries (MRTR). Genuinely long work returns a task handle the client polls. Catalog changes arrive on an opt-in subscriptions/listen stream.

Security designs for your MCP server

Public MCP deployments have already shown familiar security failures: leaked credentials, broad tokens, weak audit trails, and prompt-injection exposure. Treat the bar as high from day one.

The five recurring attack classes

What changed in 2026-07-28 authorization hardening

• Validate the iss parameter (RFC 9207) - authorization servers should return iss, and clients must validate it against the recorded issuer before redeeming the authorization code. This closes an authorization-server mix-up hole. SEP-2468
• Prefer CIMD over DCR - OAuth Dynamic Client Registration is deprecated in favor of Client ID Metadata Documents, where the client_id is an HTTPS URL serving a JSON document with client_id, client_name and redirect_uris. The answer to the very common MCP case where client and server have no prior relationship.
• Issuer-bound credentials - clients must key persisted credentials by issuer, must not reuse them with a different authorization server, and must re-register when the authorization server changes. SEP-2352
• application_type in DCR - clients must declare it, so authorization servers stop rejecting localhost redirects for desktop and CLI apps. SEP-837
• Enterprise-Managed Authorization - an official extension, stable since June 2026. The client gets an ID-JAG from the IdP during SSO and exchanges it for an access token at the MCP server's authorization server, so an organization provisions MCP access centrally and users skip the per-server OAuth dance entirely.

The compact security rule

"Every request" is now literal. With no session there is no connection-scoped "already authorized at connection time" - each request must be independently authenticated and authorized.

Security baseline for HTTP deployments

• OAuth 2.1 with PKCE - use the standard authorization flow for protected HTTP MCP servers.
• Resource Indicators (RFC 8707) - every access token must bind to the specific MCP server URI. Server rejects mismatched audience claims.
• Validate iss (RFC 9207) before redeeming an authorization code.
• Short-lived access tokens - 15-60 minutes - paired with refresh tokens.
• TLS for HTTP deployments - including internal systems unless local development is explicitly isolated.
• Human-in-the-loop for destructive actions - refunds, deletes, money movement need explicit user confirmation.
• Allow-list outbound calls - block egress to user-supplied URLs unless that is literally the tool's job.
• Never auto-dereference external $ref URIs in tool schemas, and bound the resources spent resolving composition keywords.
• Validate promoted headers - x-mcp-header values originate in model-generated tool arguments. Reject header/body mismatches rather than trusting whichever copy is convenient.

Designing MCP when you already have rich APIs

The most common starting point - and the most commonly bungled. The trap: one MCP tool per REST endpoint. It works. It's frustrating. Simple goals take five calls.

Patterns that work

A migration path

1. Stand up a thin generated server from your OpenAPI spec to validate plumbing.
2. Instrument it. Log which tools the agent actually uses for real workflows.
3. Identify the top 3-5 workflows by frequency.
4. Replace each cluster of fine-grained tools with one workflow tool.
5. Retire unused fine-grained tools, or move behind a "power user" flag.
6. Re-evaluate quarterly - usage shifts as agents and users learn what's possible.

State management - life after protocol-level sessions

The stateful-vs-stateless debate that dominated MCP architecture through 2025 and early 2026 has been settled by the spec: stateless won. The protocol no longer has sessions. State didn't disappear - it became explicit.

What was removed, and what replaced it

Where state actually lives now

The practical recipe

• Handlers are pure functions of (request, shared storage). No process-local session maps.
• Authenticate and authorize on every request. There is no connection-scoped "already checked".
• Mint explicit handles for anything spanning calls; sign them, scope them to a principal, expire them.
• Put shared state in a fast store (Redis, DynamoDB, Postgres) keyed by the handle, not by a connection.
• Hold heavy shared resources - warmed indexes, connection pools, model caches - at process or sidecar level, read-only, never keyed to a caller.
• Reap stale handles and tasks on a timer, the way you'd expire any other token.
• Use ttlMs so clients stop re-listing; use subscriptions/listen only for clients that genuinely need push.

Per-agent isolation is still your job

Architectural best practices

Consolidated from the 2026-07-28 specification, the August 2026 roadmap, and what production teams have learned the hard way.

Scope & structure

Schema & contracts

Transport & deployment

Security

Reliability

Idempotency matters more now, not less: there's no stream resumability, so a dropped response means the client will re-issue the request.

Observability

Developer experience

• README opens with three concrete agent prompts that should "just work."
• Read your tools/list out loud - if it doesn't make sense, the agent won't either.
• Local dev mode - stdio + fake auth, runs against the real server logic.
• Contract tests verifying JSON Schema of every tool's response, on every commit.
• A conformance run against the official suite (SEP-2484) - Standards Track SEPs can no longer reach Final without matching test scenarios, and the same discipline is worth borrowing.
• Quarterly review of which tools agents actually call. Remove what isn't used.
• Extensions as feature flags - they're always opt-in and disabled by default, so a beta capability can reach a subset of clients before becoming default.
• Your own deprecation policy - the spec's Active → Deprecated → Removed lifecycle with a twelve-month minimum window is a reasonable template.

The extension ecosystem

2026-07-28 formalized extensions (SEP-2133) as the way to add capability without destabilizing the core. Understanding this is now part of understanding MCP, because several things that used to be core features live here.

How extensions work

• Reverse-DNS identifiers - {vendor-prefix}/{extension-name}. Official ones use io.modelcontextprotocol/; third parties use a domain they own.
• Negotiated through the extensions map on client and server capabilities.
• Versioned independently of the core spec.
• Always disabled by default, requiring explicit developer opt-in. SDKs choose which to implement - check the SDK docs.
• Official extensions live in ext- repositories in the MCP GitHub org; incubating ones in experimental-ext- repos tied to a Working Group.

The road ahead August 2026 roadmap

Five priority areas guide the next release cycle. SEPs inside them get expedited review.

1. Agentic messaging primitives - server-initiated events (webhooks and channels) so clients stop polling for results; a composition review across the Agents, Transports and Triggers & Events Working Groups; maturing Tasks toward core inclusion.
2. HTTP-native transport unification - stretching the "an MCP server is just an HTTP workload" model to every deployment mode, including local servers speaking Streamable HTTP over stdio.
3. Agent identity & enterprise security - moving past "a person approves in a browser" to workloads with their own identity: DPoP (RFC 9449), Workload Identity Federation, the ID-JAG grant, and standard token exchange, with continued engagement in the IETF OAuth and WIMSE working groups.
4. Improved primitives - one clear contract for tool result handling, plus progressive discovery so a server can offer a small entry point and reveal more of its catalog as the conversation narrows.
5. Improved SDK developer experience - ergonomics, conformance testing and documentation, which matter more now that many developers build MCP servers by pointing an agent at the libraries.

Separately, the Server Card Working Group is defining .well-known metadata conventions so a server can be discovered and reasoned about without connecting to it.

Migrating 2025-11-25 → 2026-07-28

A practical checklist. Budget real time for this - it's a breaking change, though the SDKs absorb much of it.

Server checklist

• Delete the handshake. Remove initialize / notifications/initialized. Read protocol version and client capabilities from _meta on every request.
• Implement server/discover. It's mandatory. Return supportedVersions, capabilities, instructions, serverInfo, plus ttlMs / cacheScope.
• Remove all per-connection state. Delete session maps keyed by Mcp-Session-Id. Mint explicit signed handles instead.
• Stop making server-initiated requests. Rewrite every elicitation/create, sampling/createMessage and roots/list call site to return input_required with inputRequests and requestState, and to resume from inputResponses on the retry.
• Add resultType to every result. "complete" unless it's an MRTR interim result.
• Add ttlMs and cacheScope to server/discover, the three list methods, resources/templates/list and resources/read. Never on interim results.
• Return tools in a deterministic order.
• Replace resources/subscribe and the HTTP GET endpoint with subscriptions/listen, honoring per-type opt-in and sending the acknowledgment first.
• Drop ping, logging/setLevel and notifications/roots/list_changed. Read io.modelcontextprotocol/logLevel from _meta, and emit notifications/message only for requests that set it.
• Drop SSE resumability. Remove Last-Event-ID handling and event IDs. Make side-effecting tools idempotent - clients will re-issue lost requests.
• Validate the routing headers and return HeaderMismatch (-32020) on a mismatch.
• Renumber error codes. -32001→-32020, -32003→-32021, -32004→-32022; resource-not-found -32002→-32602.
• Move long-running work to the Tasks extension rather than blocking.
• Re-check auth on every request. There's no connection-scoped authorization any more.

Client checklist

• Send _meta on every request - protocolVersion and clientCapabilities are required; send clientInfo too.
• Handle UnsupportedProtocolVersionError (-32022) by picking a version from the supported list and retrying.
• Implement the MRTR retry loop - on input_required, fulfil each entry in inputRequests, then re-issue the original request with a new request id, same params, plus inputResponses and the echoed requestState.
• Treat a missing resultType as "complete" so legacy servers keep working.
• Honor ttlMs and cacheScope - never serve a cached response across a different method or params, and never cache an MRTR retry result.
• Send the routing headers, mirroring body values exactly, with the Base64 sentinel encoding where needed.
• Mirror x-mcp-header annotations from tool schemas into HTTP headers on HTTP transports.
• Re-issue, don't resume, when a response stream breaks.
• Migrate registration to CIMD where supported; set application_type if you still fall back to DCR; key persisted credentials by issuer.
• Validate iss before redeeming an authorization code.