Open Model Context Protocol
Version draft

5.3.1 Overview

This page defines the message patterns of the core protocol: the ways a client and server compose JSON-RPC requests, responses, and notifications into interactions. Every transport carries all of these patterns; transports differ only in how messages are framed and delivered.

Every interaction begins with the client:

• The client sends JSON-RPC requests and notifications.
• The server answers each request with a JSON-RPC response (a result or error), optionally preceded by notifications scoped to that request.

Servers MUST NOT initiate JSON-RPC requests, and clients do not send JSON-RPC responses.

Request and Response

The client sends a request; the server answers it with a result or an error. While the request is in flight, the server MAY send notifications scoped to it, such as notifications/progress and notifications/message.

Multi Round-Trip Requests

When a server needs client input (sampling, elicitation, or roots) to complete a request, it answers with an InputRequiredResult and the client retries the request with the matching inputResponses. See Multi Round-Trip Requests.

Subscribe and Notify

To receive change notifications (list changes, resource updates), the client sends a subscriptions/listen request; the reply is a long-lived stream of the requested notification types. Stream state is scoped to the request: if the underlying channel is lost, the client re-issues the request.

Adding Patterns

All core protocol features are built from these patterns. A protocol revision that adds a pattern defines it on this page. Transports carry new patterns without changes, because patterns are expressed entirely in terms of requests, responses, and notifications.

5.3.2 Multi Round-Trip Requests

Multi Round-Trip Requests

The Model Context Protocol (MCP) defines several ways for servers to request additional information from users during the processing of client requests (such as roots/list, sampling/createMessage, or elicitation/create). The multi round-trip requests pattern provides a standardized way to handle these server-requests without requiring a shared storage layer across server instances or requiring stateful load balancing.

The high level flow functions as follows:

1. Client sends an initial request to the server with the parameters needed to perform the operation.
2. Server determines that additional information is required to fulfill the request and responds requesting more information.
3. Client gathers the requested information from the user or other sources, then retries the original request including the additional requested information.
4. Server determines it has sufficient information to complete the operation, and responds with the final result.

Core Types

This flow is implemented in MCP using the following Types.

InputRequests

An InputRequests object is a map of server-client requests. Keys are server-assigned string identifiers; values are request objects (e.g., ElicitRequest, CreateMessageRequest, or ListRootsRequest).

{
  "github_login": {
    "method": "elicitation/create",
    "params": {
      "mode": "form",
      "message": "Please provide your GitHub username",
      "requestedSchema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" }
        },
        "required": ["name"]
      }
    }
  },
  "capital_of_france": {
    "method": "sampling/createMessage",
    "params": {
      "messages": [
        {
          "role": "user",
          "content": {
            "type": "text",
            "text": "What is the capital of France?"
          }
        }
      ],
      "systemPrompt": "You are a helpful assistant.",
      "maxTokens": 100
    }
  }
}

InputResponses

An InputResponses object is a map of client responses to the server requests. Keys correspond to the keys in the InputRequests map; values are the client's result for each request (e.g., ElicitResult, CreateMessageResult, or ListRootsResult).

{
  "github_login": {
    "action": "accept",
    "content": {
      "name": "octocat"
    }
  },
  "capital_of_france": {
    "role": "assistant",
    "content": {
      "type": "text",
      "text": "The capital of France is Paris."
    },
    "model": "claude-3-sonnet-20240307",
    "stopReason": "endTurn"
  }
}

InputRequiredResult

An InputRequiredResult is a type of Result, indicating that additional input is needed before the request can be completed.

• inputRequests (optional): An InputRequests map of server-initiated requests that the client must fulfill.
• requestState (optional): An opaque string meaningful only to the server. Clients MUST NOT inspect, parse, modify, or make any assumptions about its contents.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "input_required",
    "inputRequests": {
      // Elicitation request.
      "github_login": {
        "method": "elicitation/create",
        "params": {
          "mode": "form",
          "message": "Please provide your GitHub username",
          "requestedSchema": {
            "type": "object",
            "properties": {
              "name": { "type": "string" }
            },
            "required": ["name"]
          }
        }
      },
      // Sampling request.
      "capital_of_france": {
        "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
        }
      }
    },
    "requestState": "AEAD-protected blob"
  }
}

Supported Requests

Servers MAY send InputRequiredResult responses on the following client requests:

Servers MUST NOT send InputRequiredResult responses on any other client requests.

Basic Workflow

The basic workflow describes how a server can request additional input from the client as part of a client-server request. In this example we use tools/call as the client request, but the same pattern applies to any of the supported requests listed above.

Notably, it allows servers to request additional information without maintaining any server-side state. The server encodes any needed context into the requestState field, which the client echoes back on retry.

Note that the requests in each step are completely independent: the server processing the retry does not need any information beyond what is directly present in the retry request.

Server Requirements (Basic Workflow)

1. Servers MAY respond to any supported client request with an InputRequiredResult.

2. The InputRequiredResult MAY include an inputRequests field.

   • inputRequests keys are server assigned identifiers and MUST be unique within the scope of the request.
   • inputRequests values are request objects that MUST be one of ElicitRequest, CreateMessageRequest, or ListRootsRequest

3. The InputRequiredResult MAY include a requestState field. If specified, this field is an opaque string meaningful only to the server. Servers are free to encode the state in any format (e.g. base64-encoded JSON, encrypted JWT, serialized binary).

4. If a client request contains a requestState field, servers MUST treat requestState as an attacker-controlled input. If requestState influences authorization, resource access, or business logic, servers MUST protect its integrity (e.g. HMAC or AEAD) and MUST reject state that fails verification. Integrity protection MAY be omitted only when tampering can cause nothing worse than request failure.

5. To prevent replay, servers SHOULD include the following inside the integrity-protected requestState payload and verify each on receipt:

   • the authenticated principal, rejecting state presented by a different principal.
   • a short expiry (TTL), rejecting state presented after it lapses;
   • an identifier for the originating request, e.g. the method name and a digest of its salient parameters, rejecting state presented on a request that does not match.

6. Servers MUST include at least one of inputRequests or requestState in every InputRequiredResult response.

7. Servers MUST NOT send an inputRequests that the client has not declared support for in its capabilities. For example, if a client does not declare support for elicitation, the server MUST NOT include any elicitation/create requests in the inputRequests field.

8. Servers MUST NOT assume that clients will fulfill the inputRequests or retry the original request. Servers MAY choose to return an InputRequiredResult on multiple attempts at the same request if they want to repeatedly prompt the user for information until they have what they need to complete the request.

Client Requirements (Basic Workflow)

1. If a client receives an InputRequiredResult that contains the inputRequests field, the client MUST construct the requested inputs before retrying the original request. If the InputRequiredResult does not contain the inputRequests field, the client MAY retry the original request immediately.
2. If an InputRequiredResult contains the requestState field, the client MUST echo back the exact value of that field when retrying the original request. Clients MUST NOT inspect, parse, modify, or make any assumptions about the requestState contents. If the InputRequiredResult does not contain a requestState field, the client MUST NOT include one in the retry.
3. The JSON-RPC id MUST be different between the initial request and the retry, as they are independent requests.
4. Both the inputRequests and requestState fields affect only the client's retry of the original request. They MUST NOT be used for any other request that the client may be sending in parallel.

Error Handling

Servers SHOULD validate that the data provided by the client is a valid InputResponses object and that the information inside can be correctly parsed. Protocol errors (malformed JSON, invalid schema, internal server errors) SHOULD return a JSON-RPC error response with an appropriate error code and message.

If additional, unexpected parameters are provided in the InputResponses object, the server SHOULD ignore any information it does not recognize or need.

If the client fails to send all the information requested in a previous InputRequests, and the missing information is necessary for the server to process the request, the server SHOULD respond with a new InputRequiredResult requesting the missing information again, rather than returning an error.

Security Considerations

Because requestState passes through the client, malicious or compromised clients could attempt to modify it to alter server behavior, bypass authorization checks, or corrupt server logic. Servers MUST validate request state as described in the server requirements above.

5.3.3 Subscriptions

subscriptions/listen opens a long-lived notification stream from the server to the client. Unlike one-off requests, the stream stays open and delivers notifications until the client cancels it. It replaces the former resources/subscribe RPC and the HTTP GET endpoint.

Opening a Stream

The client sends a subscriptions/listen request with a notifications filter specifying which event types it wants to receive. The server MUST NOT send notification types the client has not explicitly requested.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscriptions/listen",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    },
    "notifications": {
      "toolsListChanged": true,
      "resourceSubscriptions": ["file:///project/config.json"]
    }
  }
}

Notification Filter

All fields are optional. Omitting a field is equivalent to not subscribing to that notification type.

Acknowledgment

The server MUST send notifications/subscriptions/acknowledged as the first message carrying the subscription's ID in _meta under io.modelcontextprotocol/subscriptionId, and MUST NOT send any notification on the subscription before it. On stdio, where every subscription shares one channel, this ordering is defined per subscription ID and not per channel: messages belonging to other subscriptions MAY be interleaved before it.

The notifications field in the acknowledgment reflects the subset the server agreed to honor. Notification types the server does not support are omitted.

{
  "jsonrpc": "2.0",
  "method": "notifications/subscriptions/acknowledged",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/subscriptionId": 1
    },
    "notifications": {
      "toolsListChanged": true,
      "resourceSubscriptions": ["file:///project/config.json"]
    }
  }
}

The client SHOULD check the acknowledged filter against what it requested and handle any unsupported types gracefully.

Receiving Notifications

All notifications delivered on the stream carry io.modelcontextprotocol/subscriptionId in _meta, identifying the subscriptions/listen request that opened the stream. The value is the JSON-RPC ID of the subscriptions/listen request. In the examples above, the request used "id": 1, so the acknowledgment and all subsequent notifications carry the subscription ID 1. On stdio, where all messages share a single channel, clients MUST use this field to correlate notifications with their originating subscription.

{
  "jsonrpc": "2.0",
  "method": "notifications/resources/updated",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/subscriptionId": 1
    },
    "uri": "file:///project/config.json"
  }
}

Multiple Concurrent Subscriptions

A client MAY have multiple active subscriptions concurrently — for example, one listening for tools-list changes and another for resource updates. Each subscription is identified by the JSON-RPC request ID of its subscriptions/listen request, and every notification on the stream carries that ID in io.modelcontextprotocol/subscriptionId so clients can demultiplex them.

Cancellation

A subscription ends when:

• The client cancels it — close the SSE stream (HTTP) or send notifications/cancelled referencing the subscriptions/listen request ID (stdio).
• The server tears it down (e.g., during shutdown) — it SHOULD send a successful subscriptions/listen response to signal a graceful end (see Graceful Closure), then close the stream.
• The underlying transport closes (HTTP timeout, TCP disconnect, stdio process exit).

Graceful Closure

When the server ends a subscription on its own initiative (for example, during shutdown), it SHOULD respond to the original subscriptions/listen request with a completion result before closing the stream. The result carries no method-specific data beyond the standard result fields and subscription metadata. This is the JSON-RPC response to the long-lived request, correlated by its id, and signals that the subscription ended gracefully — as opposed to an abrupt transport drop, which carries no response.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "complete",
    "_meta": {
      "io.modelcontextprotocol/subscriptionId": 1
    }
  }
}

Like every other message on the stream, the response carries io.modelcontextprotocol/subscriptionId in _meta, identifying which subscription it closes. The value matches the JSON-RPC id of the originating subscriptions/listen request.

A client that receives this response knows the subscription closed cleanly; a transport that closes without it indicates an unexpected disconnect, which the client MAY treat as a trigger to reconnect.

On stdio, if the connection is terminated and then re-established, the client MUST re-send subscriptions/listen to re-establish its subscriptions — the server holds no subscription state across reconnections.

See Cancellation for the full rules.

5.3.4 Cancellation

The Model Context Protocol (MCP) supports optional cancellation of in-progress requests through notification messages. A client SHOULD send a cancellation notification to indicate that a request it previously issued should be terminated.

A server MUST send notifications/cancelled referencing a subscriptions/listen request ID when it tears down that subscription stream (see Subscriptions). Servers MUST NOT send notifications/cancelled for any other purpose.

Cancellation Flow

When a client wants to cancel an in-progress request, it sends a notifications/cancelled notification containing:

• The ID of the request to cancel
• An optional reason string that can be logged or displayed

{
  "jsonrpc": "2.0",
  "method": "notifications/cancelled",
  "params": {
    "requestId": "123",
    "reason": "User requested cancellation"
  }
}

Transport-Specific Cancellation

How a client signals cancellation depends on the transport:

• Streamable HTTP: Closing the SSE response stream is the cancellation signal. The server MUST treat a client disconnect as cancellation of that request. No notifications/cancelled message is required or expected.
• stdio: There is no per-request stream to close. The client MUST send a notifications/cancelled notification referencing the request ID.

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 cancel the request and stop waiting for a response. As described in Transport-Specific Cancellation, this means:

• Streamable HTTP: closing the response stream for the request, which constitutes cancellation.
• stdio: sending a notifications/cancelled notification referencing the request ID.

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.

Behavior Requirements

1. Cancellation notifications MUST only reference requests that:
   • Were previously issued by the client
   • Are believed to still be in-progress
2. Server-sent cancellation notifications MUST reference a subscriptions/listen request, to terminate that subscription stream
3. Servers receiving cancellation notifications SHOULD:
   • Stop processing the cancelled request
   • Free associated resources
   • Not send a response for the cancelled request
4. Servers MAY ignore cancellation notifications if:
   • The referenced request is unknown
   • Processing has already completed
   • The request cannot be cancelled
5. The client SHOULD ignore any response to the cancelled request that arrives afterward

Timing Considerations

Due to network latency, cancellation notifications may arrive after request processing has completed, and potentially after a response has already been sent.

Both parties MUST handle these race conditions gracefully:

Implementation Notes

• Both parties SHOULD log cancellation reasons for debugging
• Application UIs SHOULD indicate when cancellation is requested

Error Handling

Invalid cancellation notifications SHOULD be ignored:

• Unknown request IDs
• Already completed requests
• Malformed notifications

This maintains the "fire and forget" nature of notifications while allowing for race conditions in asynchronous communication.

5.3.5 Progress

The Model Context Protocol (MCP) supports optional progress tracking for long-running operations through notification messages. The server MAY send progress notifications to report the status of requests the client has issued.

Progress Flow

When a client wants to receive progress updates for a request, it includes a progressToken in the request metadata.

• Progress tokens MUST be a string or integer value
• Progress tokens can be chosen by the client using any means, but MUST be unique across all active requests.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "some_method",
  "params": {
    "_meta": {
      "progressToken": "abc123"
    }
  }
}

The server MAY then send progress notifications containing:

• The original progress token
• The current progress value so far
• An optional "total" value
• An optional "message" value

{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "abc123",
    "progress": 50,
    "total": 100,
    "message": "Reticulating splines..."
  }
}

• The progress value MUST increase with each notification, even if the total is unknown.
• The progress and the total values MAY be floating point.
• The message field SHOULD provide relevant human readable progress information.

Behavior Requirements

1. Progress notifications MUST only reference tokens that:

   • Were provided in an active request
   • Are associated with an in-progress operation

2. Servers receiving a request with a progress token MAY:

   • Choose not to send any progress notifications
   • Send notifications at whatever frequency they deem appropriate
   • Omit the total value if unknown

Implementation Notes

• Clients and servers SHOULD track active progress tokens
• Both parties SHOULD implement rate limiting to prevent flooding
• Progress notifications MUST stop after completion

5.4.1 Overview

This page defines what a transport must provide to carry MCP messages, the standard transport bindings, and the requirements for defining new ones.

Protocol semantics are identical on every transport. A transport is a binding: it defines how messages are framed and delivered, how request metadata is carried, and how cancellation and termination are signaled. It does not define what the messages mean: the message patterns are part of the core protocol and are the same on every binding. The binding pages specify the standard transports:

1. stdio: newline-delimited messages over the standard streams of a client-launched subprocess.
2. Streamable HTTP: each message is an HTTP POST to a single MCP endpoint; replies arrive as a JSON object or a request-scoped SSE stream.

It is also possible for clients and servers to implement custom transports.

Messages

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

A binding MUST deliver client-sent requests and notifications to the server, and server-sent responses and notifications to the client. No other message direction exists: per the message patterns, servers do not initiate JSON-RPC requests and clients do not send JSON-RPC responses.

Request Metadata

All protocol metadata travels in the message body: every request carries its protocol version and client capabilities in _meta.io.modelcontextprotocol/* fields.

A binding MAY additionally mirror selected body fields into envelope metadata. The Streamable HTTP transport mirrors them into HTTP headers so that intermediaries can route and inspect requests without parsing the body. The body remains the source of truth; bindings that mirror metadata define how mismatches are rejected.

Cancellation

Each binding defines how a client abandons an in-flight request: on stdio the client sends a notifications/cancelled notification; on Streamable HTTP it closes the request's response stream. The protocol-level rules are the same everywhere; see Cancellation.

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 preserve the JSON-RPC message format, the message patterns, and the per-request metadata model. Custom transports SHOULD document their connection establishment, message framing, and cancellation patterns to aid interoperability.

Custom transports that run over a reliable bidirectional byte stream (e.g., Unix domain sockets or TCP) SHOULD reuse the stdio framing rather than defining a new one: the stdio binding is just newline-delimited JSON-RPC over a byte stream, and only its process-lifecycle rules are specific to standard streams.

Backward Compatibility

Earlier protocol revisions established a connection-scoped session with an initialize handshake and allowed servers to initiate JSON-RPC requests. Clients and servers that interoperate with those revisions detect the counterpart's era and fall back as described in Versioning: Backward Compatibility, which includes a compatibility matrix for implementors. Each binding page describes its transport-specific detection mechanics.

5.4.2 stdio

In the stdio transport, the client launches the MCP server as a subprocess. The two ends communicate over the subprocess's standard streams:

• The server reads JSON-RPC messages from stdin and writes JSON-RPC messages to stdout.
• Each message is a single JSON-RPC request, notification, or response.
• Messages are delimited by newlines, and MUST NOT contain embedded newlines.
• The server MAY write UTF-8 strings to 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.

Standard streams are the canonical channel, but nothing in this binding depends on them except the process lifecycle. The wire format (one newline-delimited JSON-RPC message per line over a reliable bidirectional byte stream) works unchanged over Unix domain sockets, TCP connections, or any similar channel. Custom transports built on such streams SHOULD reuse this framing and the message rules on this page; only the subprocess-specific aspects (launch, stderr, shutdown by closing the stream, process restart) need channel-specific equivalents.

Sending Messages

The client sends messages by writing JSON-RPC requests and notifications to the server's stdin, one message per line. The client MUST NOT write JSON-RPC responses.

Receiving Messages

The client reads server messages from stdout, one message per line. All messages share this single channel; there are no per-request streams.

The server writes three kinds of messages:

1. Responses to client requests, correlated by JSON-RPC id.
2. Notifications that relate to an in-flight request, such as notifications/progress and notifications/message.
3. Notifications delivered for an active subscriptions/listen request. Clients MUST correlate these using the io.modelcontextprotocol/subscriptionId field in _meta; see SubscriptionsListenRequest.

The server MUST NOT write JSON-RPC requests to stdout. Server-to-client interactions are carried in InputRequiredResult replies; see Multi Round-Trip Requests.

Request Metadata

All request metadata for the stdio transport is carried inline in the JSON-RPC message body. The protocol version, per-request capabilities, and optional client identity live in _meta.io.modelcontextprotocol/*; the method name and arguments live where JSON-RPC puts them. There is no header layer.

Cancellation

To cancel an in-flight request, the client MUST send a notifications/cancelled notification referencing the request's ID. Because stdio is a single shared bidirectional channel, there is no per-request stream to close. Servers SHOULD stop work on a cancelled request as soon as practical and MUST NOT send any further messages for it. See Cancellation for the full rules.

Shutdown

The client SHOULD initiate shutdown by:

1. Closing the input stream to the child process (the server).
2. Waiting for the server to exit.
3. If the server does not exit within a reasonable time, forcibly terminating the process using the mechanism appropriate for the operating system.

On POSIX systems, forced termination typically escalates from SIGTERM to SIGKILL. On Windows, where POSIX signals are not available, clients can use TerminateProcess or Job Objects.

Servers SHOULD exit promptly when their standard input is closed or reads return end-of-file. This is the primary graceful-shutdown signal and the only portable one, so honoring it reduces the need for forced termination.

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

Unexpected Termination

If the server process exits unexpectedly, the client SHOULD restart it. Because the protocol is stateless, any in-flight requests are simply lost and the client can retry them against the fresh process. Active subscriptions/listen streams must also be re-established after restart.

Backward Compatibility

A client that supports both modern (per-request-metadata) MCP versions and a legacy version that requires an initialize handshake SHOULD probe with server/discover before sending any other request, setting its preferred modern version in _meta. The probe has three possible outcomes:

• The server returns a DiscoverResult: the server is modern. Select a mutually supported version from supportedVersions and continue.
• The server returns a recognized modern JSON-RPC error such as UnsupportedProtocolVersionError: the server is modern but does not support the requested version. Use one of the versions in its advertised supported list. Do not fall back to initialize.
• The server returns any other error, or does not respond within a reasonable timeout: the server is legacy. Fall back to the initialize handshake.

The fallback MUST NOT be keyed to one specific error code: legacy servers respond to unknown pre-initialize requests with implementation-defined errors (commonly -32601 or -32602) or not at all.

A client that only supports modern versions does not need to probe, but probing is still RECOMMENDED: some legacy servers do not validate that a request arrives after initialize and would process an era-ambiguous method (such as tools/call) under legacy semantics. Probing yields a deterministic failure instead.

See Versioning: Backward Compatibility for the era model and a compatibility matrix for implementors.

5.4.3 Streamable HTTP

In the Streamable HTTP transport, the server operates as an independent process that can handle multiple client connections. At a glance:

• The server exposes a single HTTP endpoint (the MCP endpoint) that accepts POST.
• The client sends every JSON-RPC request or notification as its own HTTP POST.
• The server answers each request with either a single JSON object or a Server-Sent Events (SSE) stream scoped to that request, carrying request-related notifications followed by the final response.
• Server-to-client interactions (sampling, elicitation, roots) are embedded in results as input requests per Multi Round-Trip Requests (MRTR) (SEP-2322).
• Long-lived change notifications (such as list changes and resource updates) are delivered on the response stream of a subscriptions/listen request.

See Message Flow for sequence diagrams of these interactions.

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

Security & Endpoint

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

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.
2. The client MUST include an Accept header listing both application/json and text/event-stream as supported content types.
3. The client MUST include the request metadata headers on each POST request.
4. The body of the HTTP POST MUST be a single JSON-RPC request or notification. The client MUST NOT send JSON-RPC responses.
5. If the body is a JSON-RPC notification:
   • If the server accepts it, the server MUST return HTTP status code 202 Accepted with no body.
   • If the server cannot accept it, 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.
6. If the body is a JSON-RPC request, the server MUST return either Content-Type: application/json (a single JSON object) or Content-Type: text/event-stream (an SSE response stream). The client MUST support both.

Receiving Messages

When the server returns an SSE response stream (Content-Type: text/event-stream):

• The server MAY send JSON-RPC notifications — for example, notifications/progress or notifications/message — before the final response. These notifications MUST relate to the originating client request.
• The server MUST NOT send independent JSON-RPC requests on this stream. Server-to-client interactions (sampling, elicitation, list-roots) are embedded as input requests inside an InputRequiredResult per MRTR (SEP-2322), not delivered as separate requests on this or any other stream. This is a change from Streamable HTTP in protocol versions 2025-03-26 through 2025-11-25, where servers could send such requests on SSE streams.
• The final JSON-RPC response SHOULD terminate the stream.

Long-lived notification streams are obtained by sending a subscriptions/listen request. The server's response is itself an SSE stream that stays open and delivers the change notifications the client opted in to (such as notifications/tools/list_changed or notifications/resources/updated). Request-scoped notifications like notifications/progress and notifications/message are not delivered on the listen stream — they flow only on the response stream of the request they relate to.

When initiating an SSE stream, servers SHOULD include the X-Accel-Buffering: no header in the HTTP response. This instructs reverse proxies (such as nginx) to disable response buffering, ensuring that SSE events are delivered to clients immediately rather than being held in a buffer. Without this header, proxies may accumulate messages before sending them to the client, introducing unwanted latency and potentially breaking the real-time nature of SSE communication.

Resumable SSE streams via Last-Event-ID are not supported.

Message Flow

The following diagrams illustrate the message flows on a single MCP endpoint.

Requests and responses. Each request is its own POST; the server chooses per request whether to respond with a single JSON object or an SSE stream:

Server-to-client interactions (MRTR). When the server needs input from the client — sampling, elicitation, or roots — it does not send its own JSON-RPC request. It returns an InputRequiredResult containing inputRequests, and the client retries the original request with the matching inputResponses (see Multi Round-Trip Requests):

Change notifications. Clients that want server-initiated change notifications open a long-lived stream with subscriptions/listen; the response stream stays open and carries only the notification types the client opted in to:

Cancellation

Closing the SSE response stream MUST be treated by the server as cancellation of that request. Because each request has its own response stream, the transport-level disconnect is unambiguous. The server SHOULD stop work on the cancelled request as soon as practical and MUST NOT send any further messages for it. See Cancellation for the full rules.

Request Metadata

The Streamable HTTP transport mirrors selected JSON-RPC body fields into HTTP headers so that intermediaries (load balancers, gateways, observability tooling) can route and inspect requests without parsing the body.

Protocol Version Header

Every POST request to the MCP endpoint MUST include an MCP-Protocol-Version header.

For example: MCP-Protocol-Version: 2026-07-28

The header value MUST match the io.modelcontextprotocol/protocolVersion field carried in the request body's _meta. If the values do not match, the server MUST reject the request with 400 Bad Request and a HeaderMismatch JSON-RPC error (see Server Validation).

If the server does not implement the requested protocol version (whether the version is unknown to the server, or is a known version the server has chosen not to support), it MUST respond with 400 Bad Request and an UnsupportedProtocolVersionError listing its supported versions. See Versioning: Protocol Version Negotiation for the negotiation flow.

If the server does not implement the requested RPC method, it MUST respond with 404 Not Found and a JSON-RPC error with code -32601 (Method not found). The JSON-RPC error body distinguishes this case from a 404 returned by a legacy HTTP+SSE server that does not host the modern MCP endpoint (see Backward Compatibility).

A server that supports clients implementing protocol versions earlier than 2025-06-18 (which did not define the MCP-Protocol-Version header) MAY treat a request that omits the header as protocol version 2025-03-26. A server that does not support such clients MUST reject a request without the header per Server Validation.

Standard Request Headers

These headers are REQUIRED for compliance.

If the Mcp-Name source value cannot be safely represented as a plain ASCII header value, clients MUST encode it using the Base64 sentinel format described in Value Encoding.

tools/call request:

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: get_weather

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "Seattle, WA"
    },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

resources/read request:

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: resources/read
Mcp-Name: file:///projects/myapp/config.json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "file:///projects/myapp/config.json",
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

Custom Headers from Tool Parameters

MCP servers MAY designate specific tool parameters to be mirrored into HTTP headers using an x-mcp-header extension property in the parameter's schema within the tool's inputSchema. See Tool Definitions for details on how to annotate tool parameters.

While the use of x-mcp-header is optional for servers, clients MUST support this feature. When a server's tool definition includes x-mcp-header annotations, conforming clients MUST mirror the designated parameter values into HTTP headers.

Schema Extension

The x-mcp-header property specifies the name portion used to construct the header name Mcp-Param-{name}.

Constraints on x-mcp-header values:

• MUST NOT be empty
• MUST match HTTP field-name token syntax (1*tchar, RFC 9110 Section 5.1)
• MUST NOT contain control characters, including carriage return (CR, \r) or line feed (LF, \n)
• MUST be case-insensitively unique among all x-mcp-header values in the inputSchema
• MUST only be applied to parameters with primitive types (integer, string, boolean). Parameters with type number are not permitted. Integer values MUST be within the safe range for integers represented using IEEE754 double-precision floating point numbers (−2⁵³+1 to 2⁵³−1)
• MUST only be applied to properties that are statically reachable from the schema root: reachable via a chain consisting solely of properties keys. The chain MUST NOT pass through items (or any other array keyword), composition keywords (oneOf, anyOf, allOf, not), conditional keywords (if/then/else), or $ref. Nested object properties are permitted as long as every step in the chain is a properties key. An x-mcp-header annotation anywhere else makes the annotation — and thus the tool definition — invalid.

Header extraction is defined as reading the instance value at the exact property path of the annotated property (the chain of properties keys leading to it). If no value is present at that path in the call arguments, the header is omitted.

Clients using the Streamable HTTP transport MUST reject tool definitions where any x-mcp-header value violates these constraints. Rejection means the client MUST exclude the invalid tool from the result of tools/list. Clients SHOULD log a warning when rejecting a tool definition, including the tool name and the reason for rejection. This ensures that a single malformed tool definition does not prevent other valid tools from being used. Clients using other transports (e.g., stdio) MAY ignore x-mcp-header annotations entirely.

Example tool definition:

{
  "name": "execute_sql",
  "description": "Execute SQL on Google Cloud Spanner",
  "inputSchema": {
    "type": "object",
    "properties": {
      "region": {
        "type": "string",
        "description": "The region to execute the query in",
        "x-mcp-header": "Region"
      },
      "query": {
        "type": "string",
        "description": "The SQL query to execute"
      }
    },
    "required": ["region", "query"]
  }
}

Resulting HTTP request:

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: execute_sql
Mcp-Param-Region: us-west1

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    },
    "name": "execute_sql",
    "arguments": {
      "region": "us-west1",
      "query": "SELECT * FROM users"
    }
  }
}

Value Encoding

Clients MUST encode parameter values before including them in HTTP headers to ensure safe transmission and prevent injection attacks.

Type conversion: Convert the parameter value to its string representation:

• string: Use the value as-is
• integer: Convert to decimal string representation (e.g., 42, -7)
• boolean: Convert to lowercase "true" or "false"

Per RFC 9110, HTTP header field values must consist of visible ASCII characters (0x21-0x7E), space (0x20), and horizontal tab (0x09). When a value cannot be safely represented as a plain ASCII header value (e.g., it contains non-ASCII characters, control characters, or has leading/trailing whitespace), clients MUST use Base64 encoding of the UTF-8 representation with the following format:

Mcp-Param-{Name}: =?base64?{Base64EncodedValue}?=

The same encoding rule applies to the Mcp-Name header value. Tool and prompt names are only SHOULD-constrained to header-safe characters, so a name (or resource URI) outside the safe set is carried as:

Mcp-Name: =?base64?{Base64EncodedValue}?=

The prefix =?base64? and suffix ?= indicate that the value is Base64-encoded. These markers are case-sensitive and MUST appear exactly as shown (lowercase). Servers and intermediaries that need to inspect these values MUST decode them accordingly. In particular, servers MUST decode an encoded Mcp-Name or Mcp-Param-{Name} value before comparing it to the corresponding request body value during Server Validation.

To avoid ambiguity, clients MUST also Base64-encode any plain-ASCII value that matches the sentinel pattern (i.e., starts with =?base64? and ends with ?=).

Encoding examples:

Client Behavior

When constructing a tools/call request via HTTP transport, the client MUST:

1. Extract the values for any standard headers from the request body (e.g., method, params.name, params.uri).
2. Append the Mcp-Method header and, if applicable, Mcp-Name header to the request.
3. Inspect the tool's inputSchema for properties marked with x-mcp-header and extract the value at each annotated property's exact property path, omitting the header when no value is present (see Schema Extension).
4. Encode the values according to the Value Encoding rules.
5. Append a Mcp-Param-{Name}: {Value} header to the request.

If the server rejects a request with a HeaderMismatch error because required Mcp-Param-* headers are missing or do not match the body, the client SHOULD call tools/list to check for changes to the tool's inputSchema, then retry the original request with the appropriate headers.

Server Behavior for Custom Headers

Intermediate servers that do not recognize an Mcp-Param-{Name} header MUST forward it and otherwise ignore it, as required by the HTTP Semantics RFC.

Servers MUST reject requests with a recognized Mcp-Param-{Name} header that contains invalid characters (see Value Encoding).

Any server that processes the message body MUST validate that encoded header values, after decoding if Base64-encoded, match the corresponding values in the request body. Servers MUST reject requests with a 400 Bad Request HTTP status and JSON-RPC error code -32020 (HeaderMismatch) if any validation fails.

Case Sensitivity

Header names (called "field names" in RFC 9110) are case-insensitive. Clients and servers MUST use case-insensitive comparisons for header names. Header values (such as method names) are case-sensitive.

Server Validation

Servers that process the request body MUST reject requests where the values specified in the headers do not match the corresponding values in the request body. This prevents potential security vulnerabilities when different components in the network rely on different sources of truth (e.g., a load balancer routing on the header value while the MCP server executes based on the body value).

When rejecting a request due to header validation failure, servers MUST return HTTP status 400 Bad Request and MUST include a JSON-RPC error response using the following error code:

This error code is allocated from the sub-range the MCP specification reserves for protocol-defined errors. See Error Codes.

Example error response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32020,
    "message": "Header mismatch: Mcp-Name header value 'foo' does not match body value 'bar'"
  }
}

Validation failure conditions include:

• A required standard header (MCP-Protocol-Version, Mcp-Method, Mcp-Name) is missing.
• A header value does not match the corresponding request body value. For headers that permit the Base64 sentinel encoding (Mcp-Name and Mcp-Param-{Name}), servers MUST decode encoded values (see Value Encoding) before comparing them to the body value.
• A header value contains invalid characters.

Backward Compatibility

A client that supports both modern (per-request-metadata) MCP versions and a legacy version that requires an initialize handshake MAY detect which era the server implements by attempting a modern request first. On 400 Bad Request, the client SHOULD inspect the response body before falling back: modern servers also use 400 for UnsupportedProtocolVersionError, MissingRequiredClientCapabilityError, and header-validation failures.

• If the body contains a recognized modern JSON-RPC error, the server speaks a modern version of MCP — retry using the advertised supported versions or correct the request, rather than falling back.
• If the body is empty or is not a recognized modern JSON-RPC error, fall back to initialize and continue with the legacy version for subsequent requests.

See Versioning: Backward Compatibility for the era model and a compatibility matrix for implementors.

Earlier Streamable HTTP Revisions

Protocol versions 2025-03-26 through 2025-11-25 also used the Streamable HTTP transport, but in a different shape: servers could assign a session via the Mcp-Session-Id header (terminated with HTTP DELETE), clients could open a standalone SSE stream with HTTP GET to receive server-initiated messages, servers could send JSON-RPC requests on SSE streams, and streams were resumable via Last-Event-ID. None of these mechanisms are part of this revision.

A server that supports only this revision and receives such traffic from an older client SHOULD respond as follows:

• HTTP GET or DELETE to the MCP endpoint: respond with 405 Method Not Allowed.
• An Mcp-Session-Id header on a request: ignore it, and do not mint or echo session IDs.
• A Last-Event-ID header: ignore it; streams are not resumable.

Servers and clients that need to interoperate with counterparts speaking those protocol versions implement the behavior described in the corresponding revision (for example, 2025-11-25: Streamable HTTP), in addition to the version-negotiation fallback described above.

HTTP+SSE Transport (2024-11-05)

Clients and servers can maintain backward 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 a request 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 HTTP status code 400 Bad Request, 404 Not Found, or 405 Method Not Allowed and the response body is not a recognized modern JSON-RPC error (a modern server returns one for unsupported version, unknown method, or header-validation failure):
     • 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.

5.5.1 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 Bearer Token Usage (RFC6750)
• OAuth 2.0 Authorization Server Metadata (RFC8414)
• OAuth 2.0 Dynamic Client Registration Protocol (RFC7591)
• Resource Indicators for OAuth 2.0 (RFC8707)
• OAuth 2.0 Protected Resource Metadata (RFC9728)
• OAuth 2.0 Authorization Server Issuer Identification (RFC9207)
• OAuth Client ID Metadata Documents (draft-ietf-oauth-client-id-metadata-document-00)
• OpenID Connect Discovery 1.0
• OpenID Connect Dynamic Client Registration 1.0 (OpenID Connect Registration)

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. Authorization Server Discovery 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). Note that Dynamic Client Registration is deprecated and retained for backwards compatibility with authorization servers that do not support Client ID Metadata Documents.

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

MCP servers advertise their associated authorization servers through OAuth 2.0 Protected Resource Metadata, and MCP clients determine authorization server endpoints and supported capabilities through authorization server metadata discovery. Implementations MUST follow the normative discovery requirements defined in Authorization Server Discovery.

Client Registration

Before initiating the authorization flow, MCP clients MUST obtain a client ID through one of three registration mechanisms: Client ID Metadata Documents, pre-registration, or Dynamic Client Registration, following the requirements and selection priority defined in Client Registration.

Scope Selection Strategy

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 the current operation. These scopes are required to satisfy the current request. When re-authorizing, clients SHOULD include these scopes alongside any previously granted scopes to avoid losing permissions needed for other operations (see Step-Up Authorization Flow). 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"

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.

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 registration step shown in the flow uses one of the mechanisms defined in Client Registration.

The complete Authorization flow proceeds as follows:

Authorization Response Validation

Before redirecting the user-agent, the client MUST record the issuer value from the selected authorization server's validated metadata document (see Authorization Server Metadata Discovery) and associate it with the same per-request record used to store the PKCE code verifier (and the state value, if used). The validation in this section depends on that recorded value being authentic; it provides no protection if the expected issuer was obtained from an unvalidated source.

MCP authorization servers SHOULD include the iss parameter in authorization responses, including error responses, as defined in RFC9207 Section 2. Authorization servers that include the iss parameter MUST advertise this by setting authorization_response_iss_parameter_supported to true in their metadata (RFC9207 Section 2.3).

On receiving the authorization response, MCP clients MUST apply the validation in RFC9207 Section 2.4 before transmitting the authorization code to any token endpoint:

The third row applies the local-policy provision in RFC9207 Section 2.4: this specification compares a present iss against the recorded issuer regardless of metadata advertisement, to accommodate authorization servers that emit iss before updating their metadata.

A future revision of this specification is expected to upgrade authorization server inclusion of iss from SHOULD to MUST. Implementers are encouraged to emit and validate iss now to ease that transition; client rejection behavior on iss absence will continue to be keyed on authorization_response_iss_parameter_supported until that revision defines the upgrade path.

After decoding the iss value from the application/x-www-form-urlencoded response per RFC 9207 Section 2.4, clients MUST NOT apply scheme or host case folding, default-port elision, trailing-slash, or percent-encoding normalization (RFC 3986 Sections 6.2.2-6.2.3) before comparison.

This validation applies equally to error responses - on mismatch the client MUST NOT act on or display error, error_description, or error_uri.

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.

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.

Refresh Tokens

This section provides guidance for MCP Clients and MCP Servers when handling or issuing refresh tokens for both OAuth and OpenID Connect.

MCP Clients that desire refresh tokens:

• MUST keep refresh tokens confidential in transit and storage as specified in OAuth 2.1 Section 4.3
• SHOULD include refresh_token in their grant_types client metadata
• MAY add offline_access to the scope parameter of the authorization and token requests when the Authorization Server metadata contains it in scopes_supported
• MUST NOT assume refresh tokens will be issued; the AS retains discretion

MCP Servers (Protected Resources) SHOULD NOT include offline_access in WWW-Authenticate scope or Protected Resource Metadata scopes_supported, as refresh tokens are not a resource requirement.

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 operation in the scope parameter, consistent with RFC 6750 Section 3.1. The scope attribute describes the scopes necessary to access the requested resource — servers are not required to include the client's previously granted scopes.

Whatever scope-inclusion strategy a server adopts, servers SHOULD include all scopes required for the current operation in a single challenge. Challenging incrementally (returning one missing scope, then another on the subsequent retry) forces multiple authorization round-trips for a single operation and degrades user experience. The required scopes may be determined dynamically based on the specific request arguments and context, but once determined, they should be emitted together.

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.

Scope accumulation across operations is a client-side responsibility. See the Step-Up Authorization Flow for the scope-union requirement.

Example insufficient scope response:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
                         scope="files:write",
                         resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         error_description="File write permission required for this operation"

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 by computing the union of the client's previously requested scope set and the scopes from the current challenge. This ensures previously granted permissions are preserved when servers emit per-operation scope challenges per RFC 6750 Section 3.1. Clients MAY also consult the Scope Selection Strategy for initial scope selection guidance.
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.

Servers MUST account for scope hierarchies, where a broader scope implies narrower ones, when deciding whether a token is sufficient for an operation.

Security Considerations

Implementations of this specification MUST follow the normative security requirements in Security Considerations, covering token audience binding and validation, token theft, communication security, authorization code protection, mix-up and confused deputy attacks, open redirection, and Client ID Metadata Document security.

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.5.2 Authorization Server Discovery

This document 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".

When multiple authorization servers are listed in authorization_servers, each is an independent OAuth 2.0 authorization server. Consistent with RFC 6749 Section 2.2, client identifiers are unique to the authorization server that issued them. Clients MUST maintain separate registration state (client credentials, tokens) per authorization server and MUST NOT assume that credentials valid for one authorization server will be accepted by another. See Authorization Server Binding for the requirements on associating client credentials with the authorization server that issued them.

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 clients MUST be able to parse WWW-Authenticate headers and respond appropriately to HTTP 401 Unauthorized responses from the MCP server.

Servers can also include a scope parameter in the WWW-Authenticate challenge to indicate the scopes required for accessing the resource; the scope semantics and the associated client behavior are defined in the Scope Selection Strategy section.

Authorization Server Metadata Discovery

MCP uses the default oauth-authorization-server well-known URI suffix defined in RFC 8414 Section 3.1 for authorization server metadata discovery. MCP does not define an application-specific well-known URI suffix.

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 RFC 8414 Section 3.1 "Authorization Server Metadata Request" for OAuth 2.0 Authorization Server Metadata discovery and RFC 8414 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

After retrieving a metadata document, MCP clients MUST validate it as required by RFC8414 Section 3.3 or OpenID Connect Discovery Section 4.3: the issuer value in the document MUST be identical to the issuer identifier used to construct the well-known URL. If they differ, the client MUST NOT use the metadata. For example, a document fetched from https://attacker.example/.well-known/oauth-authorization-server that contains "issuer": "https://honest.example" MUST be rejected.

Sequence Diagram

The following diagram outlines an example flow:

5.5.3 Client Registration

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 use 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 that it supports them (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 for client registration.

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 and in Client ID Metadata Document Security

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://[::1]: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:

Advertising CIMD Support

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.

Pre-registration

MCP clients SHOULD support an option for static client credentials such as those supplied by a pre-registration 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.

Application Type and Redirect URI Constraints

When authorization servers support OpenID Connect (OIDC) and Dynamic Client Registration, they may enforce additional constraints on redirect URIs based on the application_type parameter as defined in OpenID Connect Dynamic Client Registration 1.0.

MCP clients MUST specify an appropriate application_type during Dynamic Client Registration. Omitting it defaults to "web" under OIDC, which can conflict with native-style redirect URIs; non-OIDC servers safely ignore the parameter.

• Native applications (desktop applications, mobile apps, CLI tools, and locally-hosted web applications accessed via localhost) SHOULD use application_type: "native"
• Web applications (remote browser-based applications served from a non-local host) SHOULD use application_type: "web"

MCP clients MUST be prepared to handle registration failures due to redirect URI constraints when authorization servers implement OIDC. When a registration request is rejected, clients SHOULD surface a meaningful error to the user or developer. Clients MAY retry registration with an adjusted application_type or with redirect URIs that conform to the authorization server's requirements for the given application type.

Authorization Server Binding

Clients that use pre-registered credentials, or persist client credentials obtained via Dynamic Client Registration, MUST associate those credentials with the specific authorization server that issued them, keyed by the authorization server's issuer identifier. When the authorization server changes (detected via updated protected resource metadata), clients MUST NOT reuse client credentials from a different authorization server and MUST re-register with the new authorization server.

Pre-registered credentials are inherently specific to a particular authorization server. If the authorization server indicated by protected resource metadata no longer matches the one the credentials were registered with, clients SHOULD surface an error rather than silently attempting to use mismatched credentials.

Client IDs based on Client ID Metadata Documents are portable across authorization servers, since they are self-hosted HTTPS URLs resolved by the authorization server on demand. No re-registration is needed when the authorization server changes.

5.5.4 Authorization Security Considerations

This document outlines security requirements that implementers MUST consider when building MCP clients and servers.

Additionally, implementors MUST follow OAuth 2.1 security best practices as outlined 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.

Mix-Up Attacks

An attacker that controls one of the authorization servers an MCP client interacts with may attempt to have the client send it an authorization code or token issued by a different, honest authorization server (a mix-up attack, described in RFC9207 Section 1). Authorization Response Validation specifies the required mitigation.

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

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.

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 for accepting Client ID Metadata Documents, as described in Section 6.4 and Section 6.8 of the Client ID Metadata Document specification.

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.

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.