Model Context Protocol Knowledge Patch

Model Context Protocol Compatibility Guidance

Use this skill when implementing or reviewing MCP authorization, transports, schemas, tools, elicitation, sampling, or tasks. Match behavior to the negotiated protocol revision; requirements that changed between revisions are called out explicitly.

Reference index

Breaking changes and required behavior

JSON-RPC batching is revision-sensitive

The 2025-03-26 revision added top-level JSON-RPC batches, but the 2025-06-18 revision removed them. For 2025-06-18, send each request, notification, or response as a separate JSON-RPC message rather than a top-level array.

Streamable HTTP framing for 2025-06-18 likewise requires each POST body to contain one JSON-RPC request, notification, or response.

The lifecycle operation is mandatory

For 2025-06-18, the lifecycle operation requirement is MUST, strengthened from SHOULD. Treat the operation as required for implementations targeting that revision.

Separate tool execution errors from protocol errors

For 2025-11-25, return tool-call input validation failures as Tool Execution Errors rather than Protocol Errors so the failure can be inspected and the tool input corrected.

Use the current schema organization

JSON Schema 2020-12 is the default dialect for 2025-11-25 MCP schemas unless another dialect is selected explicitly. Request payload schemas are standalone parameter schemas rather than being coupled to RPC method definitions.

Stable revision status

The 2026-07-28 protocol revision is stable. Behavior previously published in its release candidate is no longer prerelease guidance.

Authorization quick reference

Choose credentials by transport

Authorization is optional. HTTP transports that implement it should use OAuth 2.1, while stdio implementations should obtain credentials from the environment. PKCE is required for every client.

Servers may use authorization-code grants for users or client-credentials grants for applications. Authorization-required or invalid-token responses use HTTP 401.

Authenticate every HTTP request

Send Authorization: Bearer <access-token> on every HTTP request, including requests made within an established MCP session. Never place the token in the query string.

Invalid or expired tokens receive HTTP 401; insufficient scope receives HTTP 403. A server delegating authorization must issue its own token bound to the upstream session and synchronize both tokens' validity and lifecycle.

Bind tokens to the MCP resource

For the 2025-06-18 authorization profile, every authorization and token request must include the RFC 8707 resource parameter, even when the authorization server does not support it. Use the most specific canonical absolute MCP URI, including a distinguishing path when needed and no fragment.

The MCP server must reject tokens not issued for that resource and must not pass the inbound token through to an upstream API.

Discover authorization metadata

For 2025-06-18, an authorized MCP server must publish RFC 9728 metadata with at least one authorization_servers entry and advertise that metadata in a 401 WWW-Authenticate header. The client chooses an advertised authorization server and uses its RFC 8414 metadata.

For 2025-11-25, support both the challenge's resource_metadata value and protected-resource well-known discovery. Follow the MCP-path and origin-root fallback order, then the documented OAuth and OIDC issuer-path order in the authorization reference.

Register clients and handle scope escalation

For 2025-11-25 clients and authorization servers without a prior relationship, Client ID Metadata Documents are the preferred registration path when client_id_metadata_document_supported is true. Dynamic registration and user-entered credentials are fallbacks.

For initial authorization, use the scope from the 401 challenge; otherwise request all scopes_supported values or omit scope when that metadata field is absent. On an insufficient-scope challenge, user-facing clients should reauthorize with the increased scope set and retry with a small retry limit.

Streamable HTTP quick reference

POST and GET roles

Streamable HTTP replaces HTTP+SSE with one MCP endpoint supporting POST and GET. Each client message uses a fresh POST with Accept listing application/json, text/event-stream.

Accepted notification- or response-only input returns an empty HTTP 202. A request returns either one JSON response or an SSE stream; clients must support both forms.

A client may separately GET with Accept: text/event-stream for server-initiated traffic. A server without that stream returns HTTP 405. The GET stream must not carry ordinary JSON-RPC responses except while replaying a previous request's stream.

Carry session and revision headers

When initialization returns Mcp-Session-Id, repeat it on every later HTTP request. A required missing ID should produce HTTP 400; a terminated or expired ID produces HTTP 404 and requires new initialization without an ID.

After initialization, send MCP-Protocol-Version on every subsequent HTTP request. Without other version information, a missing header means 2025-03-26; an invalid or unsupported value produces HTTP 400.

Resume and cancel explicitly

Reconnect SSE with GET plus Last-Event-ID. Replay is confined to the disconnected stream. Dropping the stream does not cancel its request; send an explicit CancelledNotification to cancel.

For pollable SSE, honor the server's retry delay before reconnecting, whether the original stream came from POST or GET.

Enforce HTTP security

Validate Origin on every incoming connection. Return HTTP 403 when rejecting an invalid Origin. Local servers should bind to 127.0.0.1, authenticate connections, serve authorization endpoints over HTTPS, and accept only localhost or HTTPS redirect URIs.

Interactive operations quick reference

Advertise capabilities before use

Use completions to advertise argument-completion support, and check it before relying on completion requests. Later completion requests can use context for previously resolved variables.

A client advertises capabilities.elicitation before a server sends nested elicitation/create. For 2025-11-25, negotiate form and URL modes explicitly; the legacy empty capability object is form-only and an omitted request mode defaults to "form".

Clients advertise sampling: {tools: {}} before servers include sampling tools or toolChoice. Tasks are experimental in 2025-11-25 and require capability negotiation by request category.

Return structured and linked tool results

A tool may declare outputSchema and return a matching JSON object in structuredContent. Servers must conform to the schema, clients should validate it, and servers should also serialize the JSON into a text content item for older clients.

A tool result may contain a resource_link with a fetchable or subscribable URI and resource annotations. The linked resource is not guaranteed to appear in resources/list.

Preserve sampling tool-message order

A sampling tool use must be followed, before any other message, by exactly one matching tool result. A tool-result message must contain only tool results; violations use -32602.

Poll task results

An accepted augmented request returns result.task immediately. Poll tasks/get while respecting pollInterval; optional status notifications do not replace polling. tasks/result blocks until a terminal state and then returns exactly the underlying result or JSON-RPC error.

Read interactive operations for task capability shapes, status transitions, related-task metadata, URL elicitation, form schemas, sampling content, and the remaining presentation fields.