MCP Documentation Server

[Model Context Protocol home page](https://modelcontextprotocol.io/) Version 2025-06-18 (latest) Search... Ctrl K Search... Navigation Base Protocol Authorization [Documentation](https://modelcontextprotocol.io/docs/getting-started/intro) [Specification](https://modelcontextprotocol.io/specification/2025-06-18) [Community](https://modelcontextprotocol.io/community/communication) [About MCP](https://modelcontextprotocol.io/about) On this page - [Introduction](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#introduction) - [Purpose and Scope](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#purpose-and-scope) - [Protocol Requirements](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#protocol-requirements) - [Standards Compliance](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#standards-compliance) - [Authorization Flow](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-flow) - [Roles](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#roles) - [Overview](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#overview) - [Authorization Server Discovery](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-server-discovery) - [Authorization Server Location](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-server-location) - [Server Metadata Discovery](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#server-metadata-discovery) - [Sequence Diagram](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#sequence-diagram) - [Dynamic Client Registration](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#dynamic-client-registration) - [Authorization Flow Steps](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-flow-steps) - [Resource Parameter Implementation](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#resource-parameter-implementation) - [Access Token Usage](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#access-token-usage) - [Token Requirements](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#token-requirements) - [Token Handling](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#token-handling) - [Error Handling](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#error-handling) - [Security Considerations](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#security-considerations) - [Token Audience Binding and Validation](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#token-audience-binding-and-validation) - [Token Theft](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#token-theft) - [Communication Security](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#communication-security) - [Authorization Code Protection](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-code-protection) - [Open Redirection](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#open-redirection) - [Confused Deputy Problem](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#confused-deputy-problem) - [Access Token Privilege Restriction](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#access-token-privilege-restriction) **Protocol Revision**: 2025-06-18 <h2>Introduction</h2> <h3>Purpose and Scope</h3> 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. <h3>Protocol Requirements</h3> 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. <h3>Standards Compliance</h3> 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](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13)) - OAuth 2.0 Authorization Server Metadata ( [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)) - OAuth 2.0 Dynamic Client Registration Protocol ( [RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)) - OAuth 2.0 Protected Resource Metadata ( [RFC9728](https://datatracker.ietf.org/doc/html/rfc9728)) <h2>Authorization Flow</h2> <h3>Roles</h3> A protected _MCP server_ acts as an [OAuth 2.1 resource server](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#name-roles), capable of accepting and responding to protected resource requests using access tokens.An _MCP client_ acts as an [OAuth 2.1 client](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#name-roles), 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](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-server-discovery) specifies how an MCP server indicates the location of its corresponding authorization server to a client. <h3>Overview</h3> 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 the OAuth 2.0 Dynamic Client Registration Protocol ( [RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)). 3. MCP servers **MUST** implement OAuth 2.0 Protected Resource Metadata ( [RFC9728](https://datatracker.ietf.org/doc/html/rfc9728)). MCP clients **MUST** use OAuth 2.0 Protected Resource Metadata for authorization server discovery. 4. Authorization servers **MUST** provide OAuth 2.0 Authorization Server Metadata ( [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)). MCP clients **MUST** use the OAuth 2.0 Authorization Server Metadata. <h3>Authorization Server Discovery</h3> 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. <h4>Authorization Server Location</h4> MCP servers **MUST** implement the OAuth 2.0 Protected Resource Metadata ( [RFC9728](https://datatracker.ietf.org/doc/html/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](https://datatracker.ietf.org/doc/html/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”](https://datatracker.ietf.org/doc/html/rfc9728#name-authorization-servers).MCP servers **MUST** use the HTTP header `WWW-Authenticate` when returning a _401 Unauthorized_ to indicate the location of the resource server metadata URL as described in [RFC9728 Section 5.1 “WWW-Authenticate Response”](https://datatracker.ietf.org/doc/html/rfc9728#name-www-authenticate-response).MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond appropriately to `HTTP 401 Unauthorized` responses from the MCP server. <h4>Server Metadata Discovery</h4> MCP clients **MUST** follow the OAuth 2.0 Authorization Server Metadata [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414) specification to obtain the information required to interact with the authorization server. <h4>Sequence Diagram</h4> The following diagram outlines an example flow: <h3>Dynamic Client Registration</h3> MCP clients and authorization servers **SHOULD** support the OAuth 2.0 Dynamic Client Registration Protocol [RFC7591](https://datatracker.ietf.org/doc/html/rfc7591) to allow MCP clients to obtain OAuth client IDs without user interaction. This provides a standardized way for clients to automatically register with new authorization servers, which is crucial for MCP because: - Clients may not know all possible MCP servers and their authorization servers in advance. - Manual registration would create friction for users. - It enables seamless connection to new MCP servers and their authorization servers. - Authorization servers can implement their own registration policies. Any authorization servers that _do not_ support Dynamic Client Registration need to provide alternative ways to obtain a client ID (and, if applicable, client credentials). For one of these authorization servers, MCP clients will have to either: 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). <h3>Authorization Flow Steps</h3> The complete Authorization flow proceeds as follows: <h4>Resource Parameter Implementation</h4> MCP clients **MUST** implement Resource Indicators for OAuth 2.0 as defined in [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html) 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](https://www.rfc-editor.org/rfc/rfc8707.html#name-access-token-request). <h5>Canonical Server URI</h5> 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](https://www.rfc-editor.org/rfc/rfc8707.html#section-2) and aligns with the `resource` parameter in [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728).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](https://www.rfc-editor.org/rfc/rfc8707). 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](https://www.rfc-editor.org/rfc/rfc3986), 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: Copy ``` &resource=https%3A%2F%2Fmcp.example.com ``` MCP clients **MUST** send this parameter regardless of whether authorization servers support it. <h3>Access Token Usage</h3> <h4>Token Requirements</h4> Access token handling when making requests to MCP servers **MUST** conform to the requirements defined in [OAuth 2.1 Section 5 “Resource Requests”](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-5). Specifically: 1. MCP client **MUST** use the Authorization request header field defined in [OAuth 2.1 Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-5.1.1): Copy ``` 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: Copy ``` GET /mcp HTTP/1.1 Host: mcp.example.com Authorization: Bearer eyJhbGciOiJIUzI1NiIs... ``` <h4>Token Handling</h4> 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](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#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](https://www.rfc-editor.org/rfc/rfc8707.html#section-2). If validation fails, servers **MUST** respond according to [OAuth 2.1 Section 5.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#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.Authorization servers **MUST** only accept tokens that are valid for use with their own resources.MCP servers **MUST NOT** accept or transit any other tokens. <h3>Error Handling</h3> Servers **MUST** return appropriate HTTP status codes for authorization errors: | Status Code | Description | Usage | | --- | --- | --- | | 401 | Unauthorized | Authorization required or token invalid | | 403 | Forbidden | Invalid scopes or insufficient permissions | | 400 | Bad Request | Malformed authorization request | <h2>Security Considerations</h2> Implementations **MUST** follow OAuth 2.1 security best practices as laid out in [OAuth 2.1 Section 7. “Security Considerations”](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#name-security-considerations). <h3>Token Audience Binding and Validation</h3> [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html) 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](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#resource-parameter-implementation) section - MCP servers **MUST** validate that tokens presented to them were specifically issued for their use The [Security Best Practices document](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#token-passthrough) outlines why token audience validation is crucial and why token passthrough is explicitly forbidden. <h3>Token Theft</h3> 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](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#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”](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-4.3.1).\n\n<h3>Communication Security</h3>\n\nImplementations **MUST** follow [OAuth 2.1 Section 1.5 “Communication Security”](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-1.5).Specifically:\n\n1. All authorization server endpoints **MUST** be served over HTTPS.\n2. All redirect URIs **MUST** be either `localhost` or use HTTPS.\n\n<h3>Authorization Code Protection</h3>\n\nAn 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.\n(Further described in [OAuth 2.1 Section 7.5](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-7.5))To mitigate this, MCP clients **MUST** implement PKCE according to [OAuth 2.1 Section 7.5.2](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#section-7.5.2).\nPKCE 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.\n\n<h3>Open Redirection</h3>\n\nAn 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\nand 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](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#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.\n\n<h3>Confused Deputy Problem</h3>\n\nAttackers can exploit MCP servers acting as intermediaries to third-party APIs, leading to [confused deputy vulnerabilities](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#confused-deputy-problem).\nBy 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\nregistered client before forwarding to third-party authorization servers (which may require additional consent).\n\n<h3>Access Token Privilege Restriction</h3>\n\nAn 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:\n\n1. **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](https://www.rfc-editor.org/rfc/rfc9068.html)), 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.\n2. **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](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#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](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#token-passthrough) of the Security Best Practices guide for additional details.\n\nMCP 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](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#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](https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices#token-passthrough) 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](https://www.rfc-editor.org/rfc/rfc8707.html)\nto explicitly specify the target resource for which the token is being requested. This requirement aligns with the recommendation in\n[RFC 9728 Section 7.4](https://datatracker.ietf.org/doc/html/rfc9728#section-7.4). This ensures that access tokens are bound to their intended resources and\ncannot be misused across different services.\n