Open Model Context Protocol
Version 2025-11-25

4.1 Overview

The Model Context Protocol consists of several key components that work together:

• Base Protocol: Core JSON-RPC message types
• Lifecycle Management: Connection initialization, capability negotiation, and session control
• Authorization: Authentication and authorization framework for HTTP-based transports
• Server Features: Resources, prompts, and tools exposed by servers
• Client Features: Sampling and root directory lists provided by clients
• Utilities: Cross-cutting concerns like logging and argument completion

All implementations MUST support the base protocol and lifecycle management components. Other components MAY be implemented based on the specific needs of the application.

These protocol layers establish clear separation of concerns while enabling rich interactions between clients and servers. The modular design allows implementations to support exactly the features they need.

Messages

All messages between MCP clients and servers MUST follow the JSON-RPC 2.0 specification. The protocol defines these types of messages:

Requests

Requests are sent from the client to the server or vice versa, to initiate an operation.

{
  jsonrpc: "2.0";
  id: string | number;
  method: string;
  params?: {
    [key: string]: unknown;
  };
}

• Requests MUST include a string or integer ID.
• Unlike base JSON-RPC, the ID MUST NOT be null.
• The request ID MUST NOT have been previously used by the requestor within the same session.

Responses

Responses are sent in reply to requests, containing either the result or error of the operation.

Result Responses

Result responses are sent when the operation completes successfully.

{
  jsonrpc: "2.0";
  id: string | number;
  result: {
    [key: string]: unknown;
  }
}

• Result responses MUST include the same ID as the request they correspond to.
• Result responses MUST include a result field.
• The result MAY follow any JSON object structure.

Error Responses

Error responses are sent when the operation fails or encounters an error.

{
  jsonrpc: "2.0";
  id?: string | number;
  error: {
    code: number;
    message: string;
    data?: unknown;
  }
}

• Error responses MUST include the same ID as the request they correspond to (except in error cases where the ID could not be read due a malformed request).
• Error responses MUST include an error field with a code and message.
• Error codes MUST be integers.

Notifications

Notifications are sent from the client to the server or vice versa, as a one-way message. The receiver MUST NOT send a response.

{
  jsonrpc: "2.0";
  method: string;
  params?: {
    [key: string]: unknown;
  };
}

• Notifications MUST NOT include an ID.

Auth

MCP provides an Authorization framework for use with HTTP. Implementations using an HTTP-based transport SHOULD conform to this specification, whereas implementations using STDIO transport SHOULD NOT follow this specification, and instead retrieve credentials from the environment.

Additionally, clients and servers MAY negotiate their own custom authentication and authorization strategies.

For further discussions and contributions to the evolution of MCP's auth mechanisms, join us in GitHub Discussions to help shape the future of the protocol!

Schema

The full specification of the protocol is defined as a TypeScript schema. This is the source of truth for all protocol messages and structures.

There is also a JSON Schema, which is automatically generated from the TypeScript source of truth, for use with various automated tooling.

JSON Schema Usage

The Model Context Protocol uses JSON Schema for validation throughout the protocol. This section clarifies how JSON Schema should be used within MCP messages.

Schema Dialect

MCP supports JSON Schema with the following rules:

1. Default dialect: When a schema does not include a $schema field, it defaults to JSON Schema 2020-12
2. Explicit dialect: Schemas MAY include a $schema field to specify a different dialect
3. Supported dialects: Implementations MUST support at least 2020-12 and SHOULD document which additional dialects they support
4. Recommendation: Implementors are RECOMMENDED to use JSON Schema 2020-12.

Example Usage

Default dialect (2020-12):

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

Explicit dialect (draft-07):

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

Implementation Requirements

• Clients and servers MUST support JSON Schema 2020-12 for schemas without an explicit $schema field
• Clients and servers MUST validate schemas according to their declared or default dialect. They MUST handle unsupported dialects gracefully by returning an appropriate error indicating the dialect is not supported.
• Clients and servers SHOULD document which schema dialects they support

Schema Validation

• Schemas MUST be valid according to their declared or default dialect

General fields

_meta

The _meta property/parameter is reserved by MCP to allow clients and servers to attach additional metadata to their interactions.

Certain key names are reserved by MCP for protocol-level metadata, as specified below; implementations MUST NOT make assumptions about values at these keys.

Additionally, definitions in the schema may reserve particular names for purpose-specific metadata, as declared in those definitions.

Key name format: valid _meta key names have two segments: an optional prefix, and a name.

Prefix:

• If specified, MUST be a series of labels separated by dots (.), followed by a slash (/).
  • Labels MUST start with a letter and end with a letter or digit; interior characters can be letters, digits, or hyphens (-).
  • Implementations SHOULD use reverse DNS notation (e.g., com.example/ rather than example.com/).
• Any prefix where the second label is modelcontextprotocol or mcp is reserved for MCP use.
  • For example: io.modelcontextprotocol/, dev.mcp/, org.modelcontextprotocol.api/, and com.mcp.tools/ are all reserved.
  • However, com.example.mcp/ is NOT reserved, as the second label is example.

Name:

• Unless empty, MUST begin and end with an alphanumeric character ([a-z0-9A-Z]).
• MAY contain hyphens (-), underscores (_), dots (.), and alphanumerics in between.

icons

The icons property provides a standardized way for servers to expose visual identifiers for their resources, tools, prompts, and implementations. Icons enhance user interfaces by providing visual context and improving the discoverability of available functionality.

Icons are represented as an array of Icon objects, where each icon includes:

• src: A URI pointing to the icon resource (required). This can be:
  • An HTTP/HTTPS URL pointing to an image file
  • A data URI with base64-encoded image data
• mimeType: Optional MIME type if the server's type is missing or generic
• sizes: Optional array of size specifications (e.g., ["48x48"], ["any"] for scalable formats like SVG, or ["48x48", "96x96"] for multiple sizes)
• theme: Optional theme preference (light or dark) for the icon background

Required MIME type support:

Clients that support rendering icons MUST support at least the following MIME types:

• image/png - PNG images (safe, universal compatibility)
• image/jpeg (and image/jpg) - JPEG images (safe, universal compatibility)

Clients that support rendering icons SHOULD also support:

• image/svg+xml - SVG images (scalable but requires security precautions as noted below)
• image/webp - WebP images (modern, efficient format)

Security considerations:

Consumers of icon metadata MUST take appropriate security precautions when handling icons to prevent compromise:

• Treat icon metadata and icon bytes as untrusted inputs and defend against network, privacy, and parsing risks.
• Ensure that the icon URI is either a HTTPS or data: URI. Clients MUST reject icon URIs that use unsafe schemes and redirects, such as javascript:, file:, ftp:, ws:, or local app URI schemes.
  • Disallow scheme changes and redirects to hosts on different origins.
• Be resilient against resource exhaustion attacks stemming from oversized images, large dimensions, or excessive frames (e.g., in GIFs).
  • Consumers MAY set limits for image and content size.
• Fetch icons without credentials. Do not send cookies, Authorization headers, or client credentials.
• Verify that icon URIs are from the same origin as the server. This minimizes the risk of exposing data or tracking information to third-parties.
• Exercise caution when fetching and rendering icons as the payload MAY contain executable content (e.g., SVG with embedded JavaScript or extended capabilities).
  • Consumers MAY choose to disallow specific file types or otherwise sanitize icon files before rendering.
• Validate MIME types and file contents before rendering. Treat the MIME type information as advisory. Detect content type via magic bytes; reject on mismatch or unknown types.
  • Maintain a strict allowlist of image types.

Usage:

Icons can be attached to:

• Implementation: Visual identifier for the MCP server/client implementation
• Tool: Visual representation of the tool's functionality
• Prompt: Icon to display alongside prompt templates
• Resource: Visual indicator for different resource types

Multiple icons can be provided to support different display contexts and resolutions. Clients should select the most appropriate icon based on their UI requirements.

4.2 Lifecycle

The Model Context Protocol (MCP) defines a rigorous lifecycle for client-server connections that ensures proper capability negotiation and state management.

1. Initialization: Capability negotiation and protocol version agreement
2. Operation: Normal protocol communication
3. Shutdown: Graceful termination of the connection

Lifecycle Phases

Initialization

The initialization phase MUST be the first interaction between client and server. During this phase, the client and server:

• Establish protocol version compatibility
• Exchange and negotiate capabilities
• Share implementation details

The client MUST initiate this phase by sending an initialize request containing:

• Protocol version supported
• Client capabilities
• Client implementation information

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "sampling": {},
      "elicitation": {
        "form": {},
        "url": {}
      },
      "tasks": {
        "requests": {
          "elicitation": {
            "create": {}
          },
          "sampling": {
            "createMessage": {}
          }
        }
      }
    },
    "clientInfo": {
      "name": "ExampleClient",
      "title": "Example Client Display Name",
      "version": "1.0.0",
      "description": "An example MCP client application",
      "icons": [
        {
          "src": "https://example.com/icon.png",
          "mimeType": "image/png",
          "sizes": ["48x48"]
        }
      ],
      "websiteUrl": "https://example.com"
    }
  }
}

The server MUST respond with its own capabilities and information:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "logging": {},
      "prompts": {
        "listChanged": true
      },
      "resources": {
        "subscribe": true,
        "listChanged": true
      },
      "tools": {
        "listChanged": true
      },
      "tasks": {
        "list": {},
        "cancel": {},
        "requests": {
          "tools": {
            "call": {}
          }
        }
      }
    },
    "serverInfo": {
      "name": "ExampleServer",
      "title": "Example Server Display Name",
      "version": "1.0.0",
      "description": "An example MCP server providing tools and resources",
      "icons": [
        {
          "src": "https://example.com/server-icon.svg",
          "mimeType": "image/svg+xml",
          "sizes": ["any"]
        }
      ],
      "websiteUrl": "https://example.com/server"
    },
    "instructions": "Optional instructions for the client"
  }
}

After successful initialization, the client MUST send an initialized notification to indicate it is ready to begin normal operations:

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

• The client SHOULD NOT send requests other than pings before the server has responded to the initialize request.
• The server SHOULD NOT send requests other than pings and logging before receiving the initialized notification.

Version Negotiation

In the initialize request, the client MUST send a protocol version it supports. This SHOULD be the latest version supported by the client.

If the server supports the requested protocol version, it MUST respond with the same version. Otherwise, the server MUST respond with another protocol version it supports. This SHOULD be the latest version supported by the server.

If the client does not support the version in the server's response, it SHOULD disconnect.

Capability Negotiation

Client and server capabilities establish which optional protocol features will be available during the session.

Key capabilities include:

Capability objects can describe sub-capabilities like:

• listChanged: Support for list change notifications (for prompts, resources, and tools)
• subscribe: Support for subscribing to individual items' changes (resources only)

Operation

During the operation phase, the client and server exchange messages according to the negotiated capabilities.

Both parties MUST:

• Respect the negotiated protocol version
• Only use capabilities that were successfully negotiated

Shutdown

During the shutdown phase, one side (usually the client) cleanly terminates the protocol connection. No specific shutdown messages are defined—instead, the underlying transport mechanism should be used to signal connection termination:

stdio

For the stdio transport, the client SHOULD initiate shutdown by:

1. First, closing the input stream to the child process (the server)
2. Waiting for the server to exit, or sending SIGTERM if the server does not exit within a reasonable time
3. Sending SIGKILL if the server does not exit within a reasonable time after SIGTERM

The server MAY initiate shutdown by closing its output stream to the client and exiting.

HTTP

For HTTP transports, shutdown is indicated by closing the associated HTTP connection(s).

Timeouts

Implementations SHOULD establish timeouts for all sent requests, to prevent hung connections and resource exhaustion. When the request has not received a success or error response within the timeout period, the sender SHOULD issue a cancellation notification for that request and stop waiting for a response.

SDKs and other middleware SHOULD allow these timeouts to be configured on a per-request basis.

Implementations MAY choose to reset the timeout clock when receiving a progress notification corresponding to the request, as this implies that work is actually happening. However, implementations SHOULD always enforce a maximum timeout, regardless of progress notifications, to limit the impact of a misbehaving client or server.

Error Handling

Implementations SHOULD be prepared to handle these error cases:

• Protocol version mismatch
• Failure to negotiate required capabilities
• Request timeouts

Example initialization error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Unsupported protocol version",
    "data": {
      "supported": ["2024-11-05"],
      "requested": "1.0.0"
    }
  }
}

4.3 Transports

MCP uses JSON-RPC to encode messages. JSON-RPC messages MUST be UTF-8 encoded.

The protocol currently defines two standard transport mechanisms for client-server communication:

1. stdio, communication over standard in and standard out
2. Streamable HTTP

Clients SHOULD support stdio whenever possible.

It is also possible for clients and servers to implement custom transports in a pluggable fashion.

stdio

In the stdio transport:

• The client launches the MCP server as a subprocess.
• The server reads JSON-RPC messages from its standard input (stdin) and sends messages to its standard output (stdout).
• Messages are individual JSON-RPC requests, notifications, or responses.
• Messages are delimited by newlines, and MUST NOT contain embedded newlines.
• The server MAY write UTF-8 strings to its standard error (stderr) for any logging purposes including informational, debug, and error messages.
• The client MAY capture, forward, or ignore the server's stderr output and SHOULD NOT assume stderr output indicates error conditions.
• The server MUST NOT write anything to its stdout that is not a valid MCP message.
• The client MUST NOT write anything to the server's stdin that is not a valid MCP message.

Streamable HTTP

In the Streamable HTTP transport, the server operates as an independent process that can handle multiple client connections. This transport uses HTTP POST and GET requests. Server can optionally make use of Server-Sent Events (SSE) to stream multiple server messages. This permits basic MCP servers, as well as more feature-rich servers supporting streaming and server-to-client notifications and requests.

The server MUST provide a single HTTP endpoint path (hereafter referred to as the MCP endpoint) that supports both POST and GET methods. For example, this could be a URL like https://example.com/mcp.

Security Warning

When implementing Streamable HTTP transport:

1. Servers MUST validate the Origin header on all incoming connections to prevent DNS rebinding attacks
   • If the Origin header is present and invalid, servers MUST respond with HTTP 403 Forbidden. The HTTP response body MAY comprise a JSON-RPC error response that has no id
2. When running locally, servers SHOULD bind only to localhost (127.0.0.1) rather than all network interfaces (0.0.0.0)
3. Servers SHOULD implement proper authentication for all connections

Without these protections, attackers could use DNS rebinding to interact with local MCP servers from remote websites.

Sending Messages to the Server

Every JSON-RPC message sent from the client MUST be a new HTTP POST request to the MCP endpoint.

1. The client MUST use HTTP POST to send JSON-RPC messages to the MCP endpoint.
2. The client MUST include an Accept header, listing both application/json and text/event-stream as supported content types.
3. The body of the POST request MUST be a single JSON-RPC request, notification, or response.
4. If the input is a JSON-RPC response or notification:
   • If the server accepts the input, the server MUST return HTTP status code 202 Accepted with no body.
   • If the server cannot accept the input, it MUST return an HTTP error status code (e.g., 400 Bad Request). The HTTP response body MAY comprise a JSON-RPC error response that has no id.
5. If the input is a JSON-RPC request, the server MUST either return Content-Type: text/event-stream, to initiate an SSE stream, or Content-Type: application/json, to return one JSON object. The client MUST support both these cases.
6. If the server initiates an SSE stream:
   • The server SHOULD immediately send an SSE event consisting of an event ID and an empty data field in order to prime the client to reconnect (using that event ID as Last-Event-ID).
   • After the server has sent an SSE event with an event ID to the client, the server MAY close the connection (without terminating the SSE stream) at any time in order to avoid holding a long-lived connection. The client SHOULD then "poll" the SSE stream by attempting to reconnect.
   • If the server does close the connection prior to terminating the SSE stream, it SHOULD send an SSE event with a standard retry field before closing the connection. The client MUST respect the retry field, waiting the given number of milliseconds before attempting to reconnect.
   • The SSE stream SHOULD eventually include a JSON-RPC response for the JSON-RPC request sent in the POST body.
   • The server MAY send JSON-RPC requests and notifications before sending the JSON-RPC response. These messages SHOULD relate to the originating client request.
   • The server MAY terminate the SSE stream if the session expires.
   • After the JSON-RPC response has been sent, the server SHOULD terminate the SSE stream.
   • Disconnection MAY occur at any time (e.g., due to network conditions). Therefore:
     • Disconnection SHOULD NOT be interpreted as the client cancelling its request.
     • To cancel, the client SHOULD explicitly send an MCP CancelledNotification.
     • To avoid message loss due to disconnection, the server MAY make the stream resumable.

Listening for Messages from the Server

1. The client MAY issue an HTTP GET to the MCP endpoint. This can be used to open an SSE stream, allowing the server to communicate to the client, without the client first sending data via HTTP POST.
2. The client MUST include an Accept header, listing text/event-stream as a supported content type.
3. The server MUST either return Content-Type: text/event-stream in response to this HTTP GET, or else return HTTP 405 Method Not Allowed, indicating that the server does not offer an SSE stream at this endpoint.
4. If the server initiates an SSE stream:
   • The server MAY send JSON-RPC requests and notifications on the stream.
   • These messages SHOULD be unrelated to any concurrently-running JSON-RPC request from the client.
   • The server MUST NOT send a JSON-RPC response on the stream unless resuming a stream associated with a previous client request.
   • The server MAY close the SSE stream at any time.
   • If the server closes the connection without terminating the stream, it SHOULD follow the same polling behavior as described for POST requests: sending a retry field and allowing the client to reconnect.
   • The client MAY close the SSE stream at any time.

Multiple Connections

1. The client MAY remain connected to multiple SSE streams simultaneously.
2. The server MUST send each of its JSON-RPC messages on only one of the connected streams; that is, it MUST NOT broadcast the same message across multiple streams.
   • The risk of message loss MAY be mitigated by making the stream resumable.

Resumability and Redelivery

To support resuming broken connections, and redelivering messages that might otherwise be lost:

1. Servers MAY attach an id field to their SSE events, as described in the SSE standard.
   • If present, the ID MUST be globally unique across all streams within that session—or all streams with that specific client, if session management is not in use.
   • Event IDs SHOULD encode sufficient information to identify the originating stream, enabling the server to correlate a Last-Event-ID to the correct stream.
2. If the client wishes to resume after a disconnection (whether due to network failure or server-initiated closure), it SHOULD issue an HTTP GET to the MCP endpoint, and include the Last-Event-ID header to indicate the last event ID it received.
   • The server MAY use this header to replay messages that would have been sent after the last event ID, on the stream that was disconnected, and to resume the stream from that point.
   • The server MUST NOT replay messages that would have been delivered on a different stream.
   • This mechanism applies regardless of how the original stream was initiated (via POST or GET). Resumption is always via HTTP GET with Last-Event-ID.

In other words, these event IDs should be assigned by servers on a per-stream basis, to act as a cursor within that particular stream.

Session Management

An MCP "session" consists of logically related interactions between a client and a server, beginning with the initialization phase. To support servers which want to establish stateful sessions:

1. A server using the Streamable HTTP transport MAY assign a session ID at initialization time, by including it in an MCP-Session-Id header on the HTTP response containing the InitializeResult.
   • The session ID SHOULD be globally unique and cryptographically secure (e.g., a securely generated UUID, a JWT, or a cryptographic hash).
   • The session ID MUST only contain visible ASCII characters (ranging from 0x21 to 0x7E).
   • The client MUST handle the session ID in a secure manner, see Session Hijacking mitigations for more details.
2. If an MCP-Session-Id is returned by the server during initialization, clients using the Streamable HTTP transport MUST include it in the MCP-Session-Id header on all of their subsequent HTTP requests.
   • Servers that require a session ID SHOULD respond to requests without an MCP-Session-Id header (other than initialization) with HTTP 400 Bad Request.
3. The server MAY terminate the session at any time, after which it MUST respond to requests containing that session ID with HTTP 404 Not Found.
4. When a client receives HTTP 404 in response to a request containing an MCP-Session-Id, it MUST start a new session by sending a new InitializeRequest without a session ID attached.
5. Clients that no longer need a particular session (e.g., because the user is leaving the client application) SHOULD send an HTTP DELETE to the MCP endpoint with the MCP-Session-Id header, to explicitly terminate the session.
   • The server MAY respond to this request with HTTP 405 Method Not Allowed, indicating that the server does not allow clients to terminate sessions.

Sequence Diagram

Protocol Version Header

If using HTTP, the client MUST include the MCP-Protocol-Version: <protocol-version> HTTP header on all subsequent requests to the MCP server, allowing the MCP server to respond based on the MCP protocol version.

For example: MCP-Protocol-Version: 2025-11-25

The protocol version sent by the client SHOULD be the one negotiated during initialization.

For backwards compatibility, if the server does not receive an MCP-Protocol-Version header, and has no other way to identify the version - for example, by relying on the protocol version negotiated during initialization - the server SHOULD assume protocol version 2025-03-26.

If the server receives a request with an invalid or unsupported MCP-Protocol-Version, it MUST respond with 400 Bad Request.

Backwards Compatibility

Clients and servers can maintain backwards compatibility with the deprecated HTTP+SSE transport (from protocol version 2024-11-05) as follows:

Servers wanting to support older clients should:

• Continue to host both the SSE and POST endpoints of the old transport, alongside the new "MCP endpoint" defined for the Streamable HTTP transport.
  • It is also possible to combine the old POST endpoint and the new MCP endpoint, but this may introduce unneeded complexity.

Clients wanting to support older servers should:

1. Accept an MCP server URL from the user, which may point to either a server using the old transport or the new transport.
2. Attempt to POST an InitializeRequest to the server URL, with an Accept header as defined above:
   • If it succeeds, the client can assume this is a server supporting the new Streamable HTTP transport.
   • If it fails with the following HTTP status codes "400 Bad Request", "404 Not Found" or "405 Method Not Allowed":
     • Issue a GET request to the server URL, expecting that this will open an SSE stream and return an endpoint event as the first event.
     • When the endpoint event arrives, the client can assume this is a server running the old HTTP+SSE transport, and should use that transport for all subsequent communication.

Custom Transports

Clients and servers MAY implement additional custom transport mechanisms to suit their specific needs. The protocol is transport-agnostic and can be implemented over any communication channel that supports bidirectional message exchange.

Implementers who choose to support custom transports MUST ensure they preserve the JSON-RPC message format and lifecycle requirements defined by MCP. Custom transports SHOULD document their specific connection establishment and message exchange patterns to aid interoperability.

4.4 Authorization

Introduction

Purpose and Scope

The Model Context Protocol provides authorization capabilities at the transport level, enabling MCP clients to make requests to restricted MCP servers on behalf of resource owners. This specification defines the authorization flow for HTTP-based transports.

Protocol Requirements

Authorization is OPTIONAL for MCP implementations. When supported:

• Implementations using an HTTP-based transport SHOULD conform to this specification.
• Implementations using an STDIO transport SHOULD NOT follow this specification, and instead retrieve credentials from the environment.
• Implementations using alternative transports MUST follow established security best practices for their protocol.

Standards Compliance

This authorization mechanism is based on established specifications listed below, but implements a selected subset of their features to ensure security and interoperability while maintaining simplicity:

• OAuth 2.1 IETF DRAFT (draft-ietf-oauth-v2-1-13)
• OAuth 2.0 Authorization Server Metadata (RFC8414)
• OAuth 2.0 Dynamic Client Registration Protocol (RFC7591)
• OAuth 2.0 Protected Resource Metadata (RFC9728)
• OAuth Client ID Metadata Documents (draft-ietf-oauth-client-id-metadata-document-00)

Roles

A protected MCP server acts as an OAuth 2.1 resource server, capable of accepting and responding to protected resource requests using access tokens.

An MCP client acts as an OAuth 2.1 client, making protected resource requests on behalf of a resource owner.

The authorization server is responsible for interacting with the user (if necessary) and issuing access tokens for use at the MCP server. The implementation details of the authorization server are beyond the scope of this specification. It may be hosted with the resource server or a separate entity. The Authorization Server Discovery section specifies how an MCP server indicates the location of its corresponding authorization server to a client.

Overview

1. Authorization servers MUST implement OAuth 2.1 with appropriate security measures for both confidential and public clients.

2. Authorization servers and MCP clients SHOULD support OAuth Client ID Metadata Documents (draft-ietf-oauth-client-id-metadata-document-00).

3. Authorization servers and MCP clients MAY support the OAuth 2.0 Dynamic Client Registration Protocol (RFC7591).

4. MCP servers MUST implement OAuth 2.0 Protected Resource Metadata (RFC9728). MCP clients MUST use OAuth 2.0 Protected Resource Metadata for authorization server discovery.

5. MCP authorization servers MUST provide at least one of the following discovery mechanisms:

   • OAuth 2.0 Authorization Server Metadata (RFC8414)
   • OpenID Connect Discovery 1.0

   MCP clients MUST support both discovery mechanisms to obtain the information required to interact with the authorization server.

Authorization Server Discovery

This section describes the mechanisms by which MCP servers advertise their associated authorization servers to MCP clients, as well as the discovery process through which MCP clients can determine authorization server endpoints and supported capabilities.

Authorization Server Location

MCP servers MUST implement the OAuth 2.0 Protected Resource Metadata (RFC9728) specification to indicate the locations of authorization servers. The Protected Resource Metadata document returned by the MCP server MUST include the authorization_servers field containing at least one authorization server.

The specific use of authorization_servers is beyond the scope of this specification; implementers should consult OAuth 2.0 Protected Resource Metadata (RFC9728) for guidance on implementation details.

Implementors should note that Protected Resource Metadata documents can define multiple authorization servers. The responsibility for selecting which authorization server to use lies with the MCP client, following the guidelines specified in RFC9728 Section 7.6 "Authorization Servers".

Protected Resource Metadata Discovery Requirements

MCP servers MUST implement one of the following discovery mechanisms to provide authorization server location information to MCP clients:

1. WWW-Authenticate Header: Include the resource metadata URL in the WWW-Authenticate HTTP header under resource_metadata when returning 401 Unauthorized responses, as described in RFC9728 Section 5.1.

2. Well-Known URI: Serve metadata at a well-known URI as specified in RFC9728. This can be either:

   • At the path of the server's MCP endpoint: https://example.com/public/mcp could host metadata at https://example.com/.well-known/oauth-protected-resource/public/mcp
   • At the root: https://example.com/.well-known/oauth-protected-resource

MCP clients MUST support both discovery mechanisms and use the resource metadata URL from the parsed WWW-Authenticate headers when present; otherwise, they MUST fall back to constructing and requesting the well-known URIs in the order listed above.

MCP servers SHOULD include a scope parameter in the WWW-Authenticate header as defined in RFC 6750 Section 3 to indicate the scopes required for accessing the resource. This provides clients with immediate guidance on the appropriate scopes to request during authorization, following the principle of least privilege and preventing clients from requesting excessive permissions.

The scopes included in the WWW-Authenticate challenge MAY match scopes_supported, be a subset or superset of it, or an alternative collection that is neither a strict subset nor superset. Clients MUST NOT assume any particular set relationship between the challenged scope set and scopes_supported. Clients MUST treat the scopes provided in the challenge as authoritative for satisfying the current request. Servers SHOULD strive for consistency in how they construct scope sets but they are not required to surface every dynamically issued scope through scopes_supported.

Example 401 response with scope guidance:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         scope="files:read"

MCP clients MUST be able to parse WWW-Authenticate headers and respond appropriately to HTTP 401 Unauthorized responses from the MCP server.

If the scope parameter is absent, clients SHOULD apply the fallback behavior defined in the Scope Selection Strategy section.

Authorization Server Metadata Discovery

To handle different issuer URL formats and ensure interoperability with both OAuth 2.0 Authorization Server Metadata and OpenID Connect Discovery 1.0 specifications, MCP clients MUST attempt multiple well-known endpoints when discovering authorization server metadata.

The discovery approach is based on RFC8414 Section 3.1 "Authorization Server Metadata Request" for OAuth 2.0 Authorization Server Metadata discovery and RFC8414 Section 5 "Compatibility Notes" for OpenID Connect Discovery 1.0 interoperability.

For issuer URLs with path components (e.g., https://auth.example.com/tenant1), clients MUST try endpoints in the following priority order:

1. OAuth 2.0 Authorization Server Metadata with path insertion: https://auth.example.com/.well-known/oauth-authorization-server/tenant1
2. OpenID Connect Discovery 1.0 with path insertion: https://auth.example.com/.well-known/openid-configuration/tenant1
3. OpenID Connect Discovery 1.0 path appending: https://auth.example.com/tenant1/.well-known/openid-configuration

For issuer URLs without path components (e.g., https://auth.example.com), clients MUST try:

1. OAuth 2.0 Authorization Server Metadata: https://auth.example.com/.well-known/oauth-authorization-server
2. OpenID Connect Discovery 1.0: https://auth.example.com/.well-known/openid-configuration

Authorization Server Discovery Sequence Diagram

The following diagram outlines an example flow:

Client Registration Approaches

MCP supports three client registration mechanisms. Choose based on your scenario:

• Client ID Metadata Documents: When client and server have no prior relationship (most common)
• Pre-registration: When client and server have an existing relationship
• Dynamic Client Registration: For backwards compatibility or specific requirements

Clients supporting all options SHOULD follow the following priority order:

1. Use pre-registered client information for the server if the client has it available
2. Use Client ID Metadata Documents if the Authorization Server indicates if the server supports it (via client_id_metadata_document_supported in OAuth Authorization Server Metadata)
3. Use Dynamic Client Registration as a fallback if the Authorization Server supports it (via registration_endpoint in OAuth Authorization Server Metadata)
4. Prompt the user to enter the client information if no other option is available

Client ID Metadata Documents

MCP clients and authorization servers SHOULD support OAuth Client ID Metadata Documents as specified in OAuth Client ID Metadata Document. This approach enables clients to use HTTPS URLs as client identifiers, where the URL points to a JSON document containing client metadata. This addresses the common MCP scenario where servers and clients have no pre-existing relationship.

Implementation Requirements

MCP implementations supporting Client ID Metadata Documents MUST follow the requirements specified in OAuth Client ID Metadata Document. Key requirements include:

For MCP Clients:

• Clients MUST host their metadata document at an HTTPS URL following RFC requirements
• The client_id URL MUST use the "https" scheme and contain a path component, e.g. https://example.com/client.json
• The metadata document MUST include at least the following properties: client_id, client_name, redirect_uris
• Clients MUST ensure the client_id value in the metadata matches the document URL exactly
• Clients MAY use private_key_jwt for client authentication (e.g., for requests to the token endpoint) with appropriate JWKS configuration as described in Section 6.2 of Client ID Metadata Document

For Authorization Servers:

• SHOULD fetch metadata documents when encountering URL-formatted client_ids
• MUST validate that the fetched document's client_id matches the URL exactly
• SHOULD cache metadata respecting HTTP cache headers
• MUST validate redirect URIs presented in an authorization request against those in the metadata document
• MUST validate the document structure is valid JSON and contains required fields
• SHOULD follow the security considerations in Section 6 of Client ID Metadata Document

Example Metadata Document

{
  "client_id": "https://app.example.com/oauth/client-metadata.json",
  "client_name": "Example MCP Client",
  "client_uri": "https://app.example.com",
  "logo_uri": "https://app.example.com/logo.png",
  "redirect_uris": [
    "http://127.0.0.1:3000/callback",
    "http://localhost:3000/callback"
  ],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Client ID Metadata Documents Flow

The following diagram illustrates the complete flow when using Client ID Metadata Documents:

Discovery

Authorization servers advertise that they support clients using Client ID Metadata Documents by including the following property in their OAuth Authorization Server metadata:

{
  "client_id_metadata_document_supported": true
}

MCP clients SHOULD check for this capability and MAY fall back to Dynamic Client Registration or pre-registration if unavailable.

Preregistration

MCP clients SHOULD support an option for static client credentials such as those supplied by a preregistration flow. This could be:

1. Hardcode a client ID (and, if applicable, client credentials) specifically for the MCP client to use when interacting with that authorization server, or
2. Present a UI to users that allows them to enter these details, after registering an OAuth client themselves (e.g., through a configuration interface hosted by the server).

Dynamic Client Registration

MCP clients and authorization servers MAY support the OAuth 2.0 Dynamic Client Registration Protocol RFC7591 to allow MCP clients to obtain OAuth client IDs without user interaction. This option is included for backwards compatibility with earlier versions of the MCP authorization spec.

Scope Selection Strategy

When implementing authorization flows, MCP clients SHOULD follow the principle of least privilege by requesting only the scopes necessary for their intended operations. During the initial authorization handshake, MCP clients SHOULD follow this priority order for scope selection:

1. Use scope parameter from the initial WWW-Authenticate header in the 401 response, if provided
2. If scope is not available, use all scopes defined in scopes_supported from the Protected Resource Metadata document, omitting the scope parameter if scopes_supported is undefined.

This approach accommodates the general-purpose nature of MCP clients, which typically lack domain-specific knowledge to make informed decisions about individual scope selection. Requesting all available scopes allows the authorization server and end-user to determine appropriate permissions during the consent process.

This approach minimizes user friction while following the principle of least privilege. The scopes_supported field is intended to represent the minimal set of scopes necessary for basic functionality (see Scope Minimization), with additional scopes requested incrementally through the step-up authorization flow steps described in the Scope Challenge Handling section.

Authorization Flow Steps

The complete Authorization flow proceeds as follows:

Resource Parameter Implementation

MCP clients MUST implement Resource Indicators for OAuth 2.0 as defined in RFC 8707 to explicitly specify the target resource for which the token is being requested. The resource parameter:

1. MUST be included in both authorization requests and token requests.
2. MUST identify the MCP server that the client intends to use the token with.
3. MUST use the canonical URI of the MCP server as defined in RFC 8707 Section 2.

Canonical Server URI

For the purposes of this specification, the canonical URI of an MCP server is defined as the resource identifier as specified in RFC 8707 Section 2 and aligns with the resource parameter in RFC 9728.

MCP clients SHOULD provide the most specific URI that they can for the MCP server they intend to access, following the guidance in RFC 8707. While the canonical form uses lowercase scheme and host components, implementations SHOULD accept uppercase scheme and host components for robustness and interoperability.

Examples of valid canonical URIs:

• https://mcp.example.com/mcp
• https://mcp.example.com
• https://mcp.example.com:8443
• https://mcp.example.com/server/mcp (when path component is necessary to identify individual MCP server)

Examples of invalid canonical URIs:

• mcp.example.com (missing scheme)
• https://mcp.example.com#fragment (contains fragment)

Note: While both https://mcp.example.com/ (with trailing slash) and https://mcp.example.com (without trailing slash) are technically valid absolute URIs according to RFC 3986, implementations SHOULD consistently use the form without the trailing slash for better interoperability unless the trailing slash is semantically significant for the specific resource.

For example, if accessing an MCP server at https://mcp.example.com, the authorization request would include:

&resource=https%3A%2F%2Fmcp.example.com

MCP clients MUST send this parameter regardless of whether authorization servers support it.

Access Token Usage

Token Requirements

Access token handling when making requests to MCP servers MUST conform to the requirements defined in OAuth 2.1 Section 5 "Resource Requests". Specifically:

1. MCP client MUST use the Authorization request header field defined in OAuth 2.1 Section 5.1.1:

Authorization: Bearer <access-token>

Note that authorization MUST be included in every HTTP request from client to server, even if they are part of the same logical session.

2. Access tokens MUST NOT be included in the URI query string

Example request:

GET /mcp HTTP/1.1
Host: mcp.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Token Handling

MCP servers, acting in their role as an OAuth 2.1 resource server, MUST validate access tokens as described in OAuth 2.1 Section 5.2. MCP servers MUST validate that access tokens were issued specifically for them as the intended audience, according to RFC 8707 Section 2. If validation fails, servers MUST respond according to OAuth 2.1 Section 5.3 error handling requirements. Invalid or expired tokens MUST receive a HTTP 401 response.

MCP clients MUST NOT send tokens to the MCP server other than ones issued by the MCP server's authorization server.

MCP servers MUST only accept tokens that are valid for use with their own resources.

MCP servers MUST NOT accept or transit any other tokens.

Error Handling

Servers MUST return appropriate HTTP status codes for authorization errors:

Scope Challenge Handling

This section covers handling insufficient scope errors during runtime operations when a client already has a token but needs additional permissions. This follows the error handling patterns defined in OAuth 2.1 Section 5 and leverages the metadata fields from RFC 9728 (OAuth 2.0 Protected Resource Metadata).

Runtime Insufficient Scope Errors

When a client makes a request with an access token with insufficient scope during runtime operations, the server SHOULD respond with:

• HTTP 403 Forbidden status code (per RFC 6750 Section 3.1)
• WWW-Authenticate header with the Bearer scheme and additional parameters:
  • error="insufficient_scope" - indicating the specific type of authorization failure
  • scope="required_scope1 required_scope2" - specifying the minimum scopes needed for the operation
  • resource_metadata - the URI of the Protected Resource Metadata document (for consistency with 401 responses)
  • error_description (optional) - human-readable description of the error

Server Scope Management: When responding with insufficient scope errors, servers SHOULD include the scopes needed to satisfy the current request in the scope parameter.

Servers have flexibility in determining which scopes to include:

• Minimum approach: Include the newly-required scopes for the specific operation. Include any existing granted scopes as well, if they are required, to prevent clients from losing previously granted permissions.
• Recommended approach: Include both existing relevant scopes and newly required scopes to prevent clients from losing previously granted permissions
• Extended approach: Include existing scopes, newly required scopes, and related scopes that commonly work together

The choice depends on the server's assessment of user experience impact and authorization friction.

Servers SHOULD be consistent in their scope inclusion strategy to provide predictable behavior for clients.

Servers SHOULD consider the user experience impact when determining which scopes to include in the response, as misconfigured scopes may require frequent user interaction.

Example insufficient scope response:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
                         scope="files:read files:write user:profile",
                         resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         error_description="Additional file write permission required"

Step-Up Authorization Flow

Clients will receive scope-related errors during initial authorization or at runtime (insufficient_scope). Clients SHOULD respond to these errors by requesting a new access token with an increased set of scopes via a step-up authorization flow or handle the errors in other, appropriate ways. Clients acting on behalf of a user SHOULD attempt the step-up authorization flow. Clients acting on their own behalf (client_credentials clients) MAY attempt the step-up authorization flow or abort the request immediately.

The flow is as follows:

1. Parse error information from the authorization server response or WWW-Authenticate header
2. Determine required scopes as outlined in Scope Selection Strategy.
3. Initiate (re-)authorization with the determined scope set
4. Retry the original request with the new authorization no more than a few times and treat this as a permanent authorization failure

Clients SHOULD implement retry limits and SHOULD track scope upgrade attempts to avoid repeated failures for the same resource and operation combination.

Security Considerations

Implementations MUST follow OAuth 2.1 security best practices as laid out in OAuth 2.1 Section 7. "Security Considerations".

Token Audience Binding and Validation

RFC 8707 Resource Indicators provide critical security benefits by binding tokens to their intended audiences when the Authorization Server supports the capability. To enable current and future adoption:

• MCP clients MUST include the resource parameter in authorization and token requests as specified in the Resource Parameter Implementation section
• MCP servers MUST validate that tokens presented to them were specifically issued for their use

The Security Best Practices document outlines why token audience validation is crucial and why token passthrough is explicitly forbidden.

Token Theft

Attackers who obtain tokens stored by the client, or tokens cached or logged on the server can access protected resources with requests that appear legitimate to resource servers.

Clients and servers MUST implement secure token storage and follow OAuth best practices, as outlined in OAuth 2.1, Section 7.1.

Authorization servers SHOULD issue short-lived access tokens to reduce the impact of leaked tokens. For public clients, authorization servers MUST rotate refresh tokens as described in OAuth 2.1 Section 4.3.1 "Token Endpoint Extension".

Communication Security

Implementations MUST follow OAuth 2.1 Section 1.5 "Communication Security".

Specifically:

1. All authorization server endpoints MUST be served over HTTPS.
2. All redirect URIs MUST be either localhost or use HTTPS.

Authorization Code Protection

An attacker who has gained access to an authorization code contained in an authorization response can try to redeem the authorization code for an access token or otherwise make use of the authorization code. (Further described in OAuth 2.1 Section 7.5)

To mitigate this, MCP clients MUST implement PKCE according to OAuth 2.1 Section 7.5.2 and MUST verify PKCE support before proceeding with authorization. PKCE helps prevent authorization code interception and injection attacks by requiring clients to create a secret verifier-challenge pair, ensuring that only the original requestor can exchange an authorization code for tokens.

MCP clients MUST use the S256 code challenge method when technically capable, as required by OAuth 2.1 Section 4.1.1.

Since OAuth 2.1 and PKCE specifications do not define a mechanism for clients to discover PKCE support, MCP clients MUST rely on authorization server metadata to verify this capability:

• OAuth 2.0 Authorization Server Metadata: If code_challenge_methods_supported is absent, the authorization server does not support PKCE and MCP clients MUST refuse to proceed.

• OpenID Connect Discovery 1.0: While the OpenID Provider Metadata does not define code_challenge_methods_supported, this field is commonly included by OpenID providers. MCP clients MUST verify the presence of code_challenge_methods_supported in the provider metadata response. If the field is absent, MCP clients MUST refuse to proceed.

Authorization servers providing OpenID Connect Discovery 1.0 MUST include code_challenge_methods_supported in their metadata to ensure MCP compatibility.

Open Redirection

An attacker may craft malicious redirect URIs to direct users to phishing sites.

MCP clients MUST have redirect URIs registered with the authorization server.

Authorization servers MUST validate exact redirect URIs against pre-registered values to prevent redirection attacks.

MCP clients SHOULD use and verify state parameters in the authorization code flow and discard any results that do not include or have a mismatch with the original state.

Authorization servers MUST take precautions to prevent redirecting user agents to untrusted URI's, following suggestions laid out in OAuth 2.1 Section 7.12.2

Authorization servers SHOULD only automatically redirect the user agent if it trusts the redirection URI. If the URI is not trusted, the authorization server MAY inform the user and rely on the user to make the correct decision.

Client ID Metadata Document Security

When implementing Client ID Metadata Documents, authorization servers MUST consider the security implications detailed in OAuth Client ID Metadata Document, Section 6. Key considerations include:

Authorization Server Abuse Protection

The authorization server takes a URL as input from an unknown client and fetches that URL. A malicious client could use this to trigger the authorization server to make requests to arbitrary URLs, such as requests to private administration endpoints the authorization server has access to.

Authorization servers fetching metadata documents SHOULD consider Server-Side Request Forgery (SSRF) risks, as described in OAuth Client ID Metadata Document: Server Side Request Forgery (SSRF) Attacks.

Localhost Redirect URI Risks

Client ID Metadata Documents cannot prevent localhost URL impersonation by themselves. An attacker can claim to be any client by:

1. Providing the legitimate client's metadata URL as their client_id
2. Binding to any localhost port, and providing that address as the redirect_uri
3. Receiving the authorization code via the redirect when the user approves

The server will see the legitimate client's metadata document and the user will see the legitimate client's name, making attack detection difficult.

Authorization servers:

• SHOULD display additional warnings for localhost-only redirect URIs
• MAY require additional attestation mechanisms for enhanced security
• MUST clearly display the redirect URI hostname during authorization

Trust Policies

Authorization servers MAY implement domain-based trust policies:

• Allowlists for trusted domains (for protected servers)
• Accept any HTTPS client_id (for open servers)
• Reputation checks for unknown domains
• Restrictions based on domain age or certificate validation
• Display the CIMD and other associated client hostnames prominently to prevent phishing

Servers maintain full control over their access policies.

Confused Deputy Problem

Attackers can exploit MCP servers acting as intermediaries to third-party APIs, leading to confused deputy vulnerabilities. By using stolen authorization codes, they can obtain access tokens without user consent.

MCP proxy servers using static client IDs MUST obtain user consent for each dynamically registered client before forwarding to third-party authorization servers (which may require additional consent).

Access Token Privilege Restriction

An attacker can gain unauthorized access or otherwise compromise an MCP server if the server accepts tokens issued for other resources.

This vulnerability has two critical dimensions:

1. Audience validation failures. When an MCP server doesn't verify that tokens were specifically intended for it (for example, via the audience claim, as mentioned in RFC9068), it may accept tokens originally issued for other services. This breaks a fundamental OAuth security boundary, allowing attackers to reuse legitimate tokens across different services than intended.
2. Token passthrough. If the MCP server not only accepts tokens with incorrect audiences but also forwards these unmodified tokens to downstream services, it can potentially cause the "confused deputy" problem, where the downstream API may incorrectly trust the token as if it came from the MCP server or assume the token was validated by the upstream API. See the Token Passthrough section of the Security Best Practices guide for additional details.

MCP servers MUST validate access tokens before processing the request, ensuring the access token is issued specifically for the MCP server, and take all necessary steps to ensure no data is returned to unauthorized parties.

A MCP server MUST follow the guidelines in OAuth 2.1 - Section 5.2 to validate inbound tokens.

MCP servers MUST only accept tokens specifically intended for themselves and MUST reject tokens that do not include them in the audience claim or otherwise verify that they are the intended recipient of the token. See the Security Best Practices Token Passthrough section for details.

If the MCP server makes requests to upstream APIs, it may act as an OAuth client to them. The access token used at the upstream API is a separate token, issued by the upstream authorization server. The MCP server MUST NOT pass through the token it received from the MCP client.

MCP clients MUST implement and use the resource parameter as defined in RFC 8707 - Resource Indicators for OAuth 2.0 to explicitly specify the target resource for which the token is being requested. This requirement aligns with the recommendation in RFC 9728 Section 7.4. This ensures that access tokens are bound to their intended resources and cannot be misused across different services.

MCP Authorization Extensions

There are several authorization extensions to the core protocol that define additional authorization mechanisms. These extensions are:

• Optional - Implementations can choose to adopt these extensions
• Additive - Extensions do not modify or break core protocol functionality; they add new capabilities while preserving core protocol behavior
• Composable - Extensions are modular and designed to work together without conflicts, allowing implementations to adopt multiple extensions simultaneously
• Versioned independently - Extensions follow the core MCP versioning cycle but may adopt independent versioning as needed

A list of supported extensions can be found in the MCP Authorization Extensions repository.

5.1 Roots

The Model Context Protocol (MCP) provides a standardized way for clients to expose filesystem "roots" to servers. Roots define the boundaries of where servers can operate within the filesystem, allowing them to understand which directories and files they have access to. Servers can request the list of roots from supporting clients and receive notifications when that list changes.

User Interaction Model

Roots in MCP are typically exposed through workspace or project configuration interfaces.

For example, implementations could offer a workspace/project picker that allows users to select directories and files the server should have access to. This can be combined with automatic workspace detection from version control systems or project files.

However, implementations are free to expose roots through any interface pattern that suits their needs—the protocol itself does not mandate any specific user interaction model.

Capabilities

Clients that support roots MUST declare the roots capability during initialization:

{
  "capabilities": {
    "roots": {
      "listChanged": true
    }
  }
}

listChanged indicates whether the client will emit notifications when the list of roots changes.

Protocol Messages

Listing Roots

To retrieve roots, servers send a roots/list request:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "roots/list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "roots": [
      {
        "uri": "file:///home/user/projects/myproject",
        "name": "My Project"
      }
    ]
  }
}

Root List Changes

When roots change, clients that support listChanged MUST send a notification:

{
  "jsonrpc": "2.0",
  "method": "notifications/roots/list_changed"
}

Message Flow

Data Types

Root

A root definition includes:

• uri: Unique identifier for the root. This MUST be a file:// URI in the current specification.
• name: Optional human-readable name for display purposes.

Example roots for different use cases:

Project Directory

{
  "uri": "file:///home/user/projects/myproject",
  "name": "My Project"
}

Multiple Repositories

[
  {
    "uri": "file:///home/user/repos/frontend",
    "name": "Frontend Repository"
  },
  {
    "uri": "file:///home/user/repos/backend",
    "name": "Backend Repository"
  }
]

Error Handling

Clients SHOULD return standard JSON-RPC errors for common failure cases:

• Client does not support roots: -32601 (Method not found)
• Internal errors: -32603

Example error:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Roots not supported",
    "data": {
      "reason": "Client does not have roots capability"
    }
  }
}

Security Considerations

1. Clients MUST:

   • Only expose roots with appropriate permissions
   • Validate all root URIs to prevent path traversal
   • Implement proper access controls
   • Monitor root accessibility

2. Servers SHOULD:

   • Handle cases where roots become unavailable
   • Respect root boundaries during operations
   • Validate all paths against provided roots

Implementation Guidelines

1. Clients SHOULD:

   • Prompt users for consent before exposing roots to servers
   • Provide clear user interfaces for root management
   • Validate root accessibility before exposing
   • Monitor for root changes

2. Servers SHOULD:

   • Check for roots capability before usage
   • Handle root list changes gracefully
   • Respect root boundaries in operations
   • Cache root information appropriately

5.2 Sampling

The Model Context Protocol (MCP) provides a standardized way for servers to request LLM sampling ("completions" or "generations") from language models via clients. This flow allows clients to maintain control over model access, selection, and permissions while enabling servers to leverage AI capabilities—with no server API keys necessary. Servers can request text, audio, or image-based interactions and optionally include context from MCP servers in their prompts.

User Interaction Model

Sampling in MCP allows servers to implement agentic behaviors, by enabling LLM calls to occur nested inside other MCP server features.

Implementations are free to expose sampling through any interface pattern that suits their needs—the protocol itself does not mandate any specific user interaction model.

Tools in Sampling

Servers can request that the client's LLM use tools during sampling by providing a tools array and optional toolChoice configuration in their sampling requests. This enables servers to implement agentic behaviors where the LLM can call tools, receive results, and continue the conversation - all within a single sampling request flow.

Clients MUST declare support for tool use via the sampling.tools capability to receive tool-enabled sampling requests. Servers MUST NOT send tool-enabled sampling requests to Clients that have not declared support for tool use via the sampling.tools capability.

Capabilities

Clients that support sampling MUST declare the sampling capability during initialization:

Basic sampling:

{
  "capabilities": {
    "sampling": {}
  }
}

With tool use support:

{
  "capabilities": {
    "sampling": {
      "tools": {}
    }
  }
}

With context inclusion support (soft-deprecated):

{
  "capabilities": {
    "sampling": {
      "context": {}
    }
  }
}

Protocol Messages

Creating Messages

To request a language model generation, servers send a sampling/createMessage request:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "What is the capital of France?"
        }
      }
    ],
    "modelPreferences": {
      "hints": [
        {
          "name": "claude-3-sonnet"
        }
      ],
      "intelligencePriority": 0.8,
      "speedPriority": 0.5
    },
    "systemPrompt": "You are a helpful assistant.",
    "maxTokens": 100
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "role": "assistant",
    "content": {
      "type": "text",
      "text": "The capital of France is Paris."
    },
    "model": "claude-3-sonnet-20240307",
    "stopReason": "endTurn"
  }
}

Sampling with Tools

The following diagram illustrates the complete flow of sampling with tools, including the multi-turn tool loop:

To request LLM generation with tool use capabilities, servers include tools and optionally toolChoice in the request:

Request (Server -> Client):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "What's the weather like in Paris and London?"
        }
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name"
            }
          },
          "required": ["city"]
        }
      }
    ],
    "toolChoice": {
      "mode": "auto"
    },
    "maxTokens": 1000
  }
}

Response (Client -> Server):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "role": "assistant",
    "content": [
      {
        "type": "tool_use",
        "id": "call_abc123",
        "name": "get_weather",
        "input": {
          "city": "Paris"
        }
      },
      {
        "type": "tool_use",
        "id": "call_def456",
        "name": "get_weather",
        "input": {
          "city": "London"
        }
      }
    ],
    "model": "claude-3-sonnet-20240307",
    "stopReason": "toolUse"
  }
}

Multi-turn Tool Loop

After receiving tool use requests from the LLM, the server typically:

1. Executes the requested tool uses.
2. Sends a new sampling request with the tool results appended
3. Receives the LLM's response (which might contain new tool uses)
4. Repeats as many times as needed (server might cap the maximum number of iterations, and e.g. pass toolChoice: {mode: "none"} on the last iteration to force a final result)

Follow-up request (Server -> Client) with tool results:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "What's the weather like in Paris and London?"
        }
      },
      {
        "role": "assistant",
        "content": [
          {
            "type": "tool_use",
            "id": "call_abc123",
            "name": "get_weather",
            "input": { "city": "Paris" }
          },
          {
            "type": "tool_use",
            "id": "call_def456",
            "name": "get_weather",
            "input": { "city": "London" }
          }
        ]
      },
      {
        "role": "user",
        "content": [
          {
            "type": "tool_result",
            "toolUseId": "call_abc123",
            "content": [
              {
                "type": "text",
                "text": "Weather in Paris: 18°C, partly cloudy"
              }
            ]
          },
          {
            "type": "tool_result",
            "toolUseId": "call_def456",
            "content": [
              {
                "type": "text",
                "text": "Weather in London: 15°C, rainy"
              }
            ]
          }
        ]
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
      }
    ],
    "maxTokens": 1000
  }
}

Final response (Client -> Server):

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "role": "assistant",
    "content": {
      "type": "text",
      "text": "Based on the current weather data:\n\n- **Paris**: 18°C and partly cloudy - quite pleasant!\n- **London**: 15°C and rainy - you'll want an umbrella.\n\nParis has slightly warmer and drier conditions today."
    },
    "model": "claude-3-sonnet-20240307",
    "stopReason": "endTurn"
  }
}

Message Content Constraints

Tool Result Messages

When a user message contains tool results (type: "tool_result"), it MUST contain ONLY tool results. Mixing tool results with other content types (text, image, audio) in the same message is not allowed.

This constraint ensures compatibility with provider APIs that use dedicated roles for tool results (e.g., OpenAI's "tool" role, Gemini's "function" role).

Valid - single tool result:

{
  "role": "user",
  "content": {
    "type": "tool_result",
    "toolUseId": "call_123",
    "content": [{ "type": "text", "text": "Result data" }]
  }
}

Valid - multiple tool results:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "toolUseId": "call_123",
      "content": [{ "type": "text", "text": "Result 1" }]
    },
    {
      "type": "tool_result",
      "toolUseId": "call_456",
      "content": [{ "type": "text", "text": "Result 2" }]
    }
  ]
}

Invalid - mixed content:

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "Here are the results:"
    },
    {
      "type": "tool_result",
      "toolUseId": "call_123",
      "content": [{ "type": "text", "text": "Result data" }]
    }
  ]
}

Tool Use and Result Balance

When using tool use in sampling, every assistant message containing ToolUseContent blocks MUST be followed by a user message that consists entirely of ToolResultContent blocks, with each tool use (e.g. with id: $id) matched by a corresponding tool result (with toolUseId: $id), before any other message.

This requirement ensures:

• Tool uses are always resolved before the conversation continues
• Provider APIs can concurrently process multiple tool uses and fetch their results in parallel
• The conversation maintains a consistent request-response pattern

Example valid sequence:

1. User message: "What's the weather like in Paris and London?"
2. Assistant message: ToolUseContent (id: "call_abc123", name: "get_weather", input: {city: "Paris"}) + ToolUseContent (id: "call_def456", name: "get_weather", input: {city: "London"})
3. User message: ToolResultContent (toolUseId: "call_abc123", content: "18°C, partly cloudy") + ToolResultContent (toolUseId: "call_def456", content: "15°C, rainy")
4. Assistant message: Text response comparing the weather in both cities

Invalid sequence - missing tool result:

1. User message: "What's the weather like in Paris and London?"
2. Assistant message: ToolUseContent (id: "call_abc123", name: "get_weather", input: {city: "Paris"}) + ToolUseContent (id: "call_def456", name: "get_weather", input: {city: "London"})
3. User message: ToolResultContent (toolUseId: "call_abc123", content: "18°C, partly cloudy") ← Missing result for call_def456
4. Assistant message: Text response (invalid - not all tool uses were resolved)

Cross-API Compatibility

The sampling specification is designed to work across multiple LLM provider APIs (Claude, OpenAI, Gemini, etc.). Key design decisions for compatibility:

Message Roles

MCP uses two roles: "user" and "assistant".

Tool use requests are sent in CreateMessageResult with the "assistant" role. Tool results are sent back in messages with the "user" role. Messages with tool results cannot contain other kinds of content.

Tool Choice Modes

CreateMessageRequest.params.toolChoice controls the tool use ability of the model:

• {mode: "auto"}: Model decides whether to use tools (default)
• {mode: "required"}: Model MUST use at least one tool before completing
• {mode: "none"}: Model MUST NOT use any tools

Parallel Tool Use

MCP allows models to make multiple tool use requests in parallel (returning an array of ToolUseContent). All major provider APIs support this:

• Claude: Supports parallel tool use natively
• OpenAI: Supports parallel tool calls (can be disabled with parallel_tool_calls: false)
• Gemini: Supports parallel function calls natively

Implementations wrapping providers that support disabling parallel tool use MAY expose this as an extension, but it is not part of the core MCP specification.

Message Flow

Data Types

Messages

Sampling messages can contain:

Text Content

{
  "type": "text",
  "text": "The message content"
}

Image Content

{
  "type": "image",
  "data": "base64-encoded-image-data",
  "mimeType": "image/jpeg"
}

Audio Content

{
  "type": "audio",
  "data": "base64-encoded-audio-data",
  "mimeType": "audio/wav"
}

Model Preferences

Model selection in MCP requires careful abstraction since servers and clients may use different AI providers with distinct model offerings. A server cannot simply request a specific model by name since the client may not have access to that exact model or may prefer to use a different provider's equivalent model.

To solve this, MCP implements a preference system that combines abstract capability priorities with optional model hints:

Capability Priorities

Servers express their needs through three normalized priority values (0-1):

• costPriority: How important is minimizing costs? Higher values prefer cheaper models.
• speedPriority: How important is low latency? Higher values prefer faster models.
• intelligencePriority: How important are advanced capabilities? Higher values prefer more capable models.

Model Hints

While priorities help select models based on characteristics, hints allow servers to suggest specific models or model families:

• Hints are treated as substrings that can match model names flexibly
• Multiple hints are evaluated in order of preference
• Clients MAY map hints to equivalent models from different providers
• Hints are advisory—clients make final model selection

For example:

{
  "hints": [
    { "name": "claude-3-sonnet" }, // Prefer Sonnet-class models
    { "name": "claude" } // Fall back to any Claude model
  ],
  "costPriority": 0.3, // Cost is less important
  "speedPriority": 0.8, // Speed is very important
  "intelligencePriority": 0.5 // Moderate capability needs
}

The client processes these preferences to select an appropriate model from its available options. For instance, if the client doesn't have access to Claude models but has Gemini, it might map the sonnet hint to gemini-1.5-pro based on similar capabilities.

Error Handling

Clients SHOULD return errors for common failure cases:

• User rejected sampling request: -1
• Tool result missing in request: -32602 (Invalid params)
• Tool results mixed with other content: -32602 (Invalid params)

Example errors:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -1,
    "message": "User rejected sampling request"
  }
}

{
  "jsonrpc": "2.0",
  "id": 4,
  "error": {
    "code": -32602,
    "message": "Tool result missing in request"
  }
}

Security Considerations

1. Clients SHOULD implement user approval controls
2. Both parties SHOULD validate message content
3. Clients SHOULD respect model preference hints
4. Clients SHOULD implement rate limiting
5. Both parties MUST handle sensitive data appropriately

When tools are used in sampling, additional security considerations apply:

6. Servers MUST ensure that when replying to a stopReason: "toolUse", each ToolUseContent item is responded to with a ToolResultContent item with a matching toolUseId, and that the user message contains only tool results (no other content types)
7. Both parties SHOULD implement iteration limits for tool loops

5.3 Elicitation

The Model Context Protocol (MCP) provides a standardized way for servers to request additional information from users through the client during interactions. This flow allows clients to maintain control over user interactions and data sharing while enabling servers to gather necessary information dynamically.

Elicitation supports two modes:

• Form mode: Servers can request structured data from users with optional JSON schemas to validate responses
• URL mode: Servers can direct users to external URLs for sensitive interactions that must not pass through the MCP client

User Interaction Model

Elicitation in MCP allows servers to implement interactive workflows by enabling user input requests to occur nested inside other MCP server features.

Implementations are free to expose elicitation through any interface pattern that suits their needs—the protocol itself does not mandate any specific user interaction model.

Capabilities

Clients that support elicitation MUST declare the elicitation capability during initialization:

{
  "capabilities": {
    "elicitation": {
      "form": {},
      "url": {}
    }
  }
}

For backwards compatibility, an empty capabilities object is equivalent to declaring support for form mode only:

{
  "capabilities": {
    "elicitation": {}, // Equivalent to { "form": {} }
  },
}

Clients declaring the elicitation capability MUST support at least one mode (form or url).

Servers MUST NOT send elicitation requests with modes that are not supported by the client.

Protocol Messages

Elicitation Requests

To request information from a user, servers send an elicitation/create request.

All elicitation requests MUST include the following parameters:

The mode parameter specifies the type of elicitation:

• "form": In-band structured data collection with optional schema validation. Data is exposed to the client.
• "url": Out-of-band interaction via URL navigation. Data (other than the URL itself) is not exposed to the client.

For backwards compatibility, servers MAY omit the mode field for form mode elicitation requests. Clients MUST treat requests without a mode field as form mode.

Form Mode Elicitation Requests

Form mode elicitation allows servers to collect structured data directly through the MCP client.

Form mode elicitation requests MUST either specify mode: "form" or omit the mode field, and include these additional parameters:

Requested Schema

The requestedSchema parameter allows servers to define the structure of the expected response using a restricted subset of JSON Schema.

To simplify client user experience, form mode elicitation schemas are limited to flat objects with primitive properties only.

The schema is restricted to these primitive types:

1. String Schema

   {
     "type": "string",
     "title": "Display Name",
     "description": "Description text",
     "minLength": 3,
     "maxLength": 50,
     "pattern": "^[A-Za-z]+$",
     "format": "email",
     "default": "user@example.com"
   }
   

   Supported formats: email, uri, date, date-time

2. Number Schema

   {
     "type": "number", // or "integer"
     "title": "Display Name",
     "description": "Description text",
     "minimum": 0,
     "maximum": 100,
     "default": 50
   }
   

3. Boolean Schema

   {
     "type": "boolean",
     "title": "Display Name",
     "description": "Description text",
     "default": false
   }
   

4. Enum Schema

   Single-select enum (without titles):

   {
     "type": "string",
     "title": "Color Selection",
     "description": "Choose your favorite color",
     "enum": ["Red", "Green", "Blue"],
     "default": "Red"
   }
   

   Single-select enum (with titles):

   {
     "type": "string",
     "title": "Color Selection",
     "description": "Choose your favorite color",
     "oneOf": [
       { "const": "#FF0000", "title": "Red" },
       { "const": "#00FF00", "title": "Green" },
       { "const": "#0000FF", "title": "Blue" }
     ],
     "default": "#FF0000"
   }
   

   Multi-select enum (without titles):

   {
     "type": "array",
     "title": "Color Selection",
     "description": "Choose your favorite colors",
     "minItems": 1,
     "maxItems": 2,
     "items": {
       "type": "string",
       "enum": ["Red", "Green", "Blue"]
     },
     "default": ["Red", "Green"]
   }
   

   Multi-select enum (with titles):

   {
     "type": "array",
     "title": "Color Selection",
     "description": "Choose your favorite colors",
     "minItems": 1,
     "maxItems": 2,
     "items": {
       "anyOf": [
         { "const": "#FF0000", "title": "Red" },
         { "const": "#00FF00", "title": "Green" },
         { "const": "#0000FF", "title": "Blue" }
       ]
     },
     "default": ["#FF0000", "#00FF00"]
   }
   

Clients can use this schema to:

1. Generate appropriate input forms
2. Validate user input before sending
3. Provide better guidance to users

All primitive types support optional default values to provide sensible starting points. Clients that support defaults SHOULD pre-populate form fields with these values.

Note that complex nested structures, arrays of objects (beyond enums), and other advanced JSON Schema features are intentionally not supported to simplify client user experience.

Example: Simple Text Request

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "elicitation/create",
  "params": {
    "mode": "form",
    "message": "Please provide your GitHub username",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      },
      "required": ["name"]
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "action": "accept",
    "content": {
      "name": "octocat"
    }
  }
}

Example: Structured Data Request

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "elicitation/create",
  "params": {
    "mode": "form",
    "message": "Please provide your contact information",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Your full name"
        },
        "email": {
          "type": "string",
          "format": "email",
          "description": "Your email address"
        },
        "age": {
          "type": "number",
          "minimum": 18,
          "description": "Your age"
        }
      },
      "required": ["name", "email"]
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "action": "accept",
    "content": {
      "name": "Monalisa Octocat",
      "email": "octocat@github.com",
      "age": 30
    }
  }
}

URL Mode Elicitation Requests

URL mode elicitation enables servers to direct users to external URLs for out-of-band interactions that must not pass through the MCP client. This is essential for auth flows, payment processing, and other sensitive or secure operations.

URL mode elicitation requests MUST specify mode: "url", a message, and include these additional parameters:

The url parameter MUST contain a valid URL.

Example: Request Sensitive Data

This example shows a URL mode elicitation request directing the user to a secure URL where they can provide sensitive information (an API key, for example). The same request could direct the user into an OAuth authorization flow, or a payment flow. The only difference is the URL and the message.

Request:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "elicitation/create",
  "params": {
    "mode": "url",
    "elicitationId": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://mcp.example.com/ui/set_api_key",
    "message": "Please provide your API key to continue."
  }
}