Authentication

MCP Authorization

OAuth protected-resource metadata, client registration, and token handling for HTTP MCP servers

Summary

MCP authorization applies to HTTP-based transports. A protected MCP server acts as an OAuth 2.1 resource server; the MCP client acts as an OAuth client; an authorization server issues access tokens for the MCP server.

Authorization is optional for MCP implementations, but when an HTTP MCP server is protected it should follow the MCP authorization specification. Stdio servers should not use this flow; they should get credentials from the local environment.

MCP client → protected MCP server → protected-resource metadata
     │                    │
     └──── authorization server discovery ──── token issuance

Key pieces:

Protected-resource metadata advertises which authorization server protects the MCP endpoint.
MCP clients must use protected-resource metadata for authorization-server discovery.
Authorization servers and MCP clients should support OAuth Client ID Metadata Documents.
Dynamic client registration remains a fallback option.
Access tokens must be sent in the Authorization: Bearer <token> header and must not be placed in URLs.
Tokens must be audience-bound to the MCP server resource.

Transport Scope

MCP authorization is defined for HTTP-based transports.

Use this page for:

Streamable HTTP MCP servers exposed over HTTPS
remote MCP servers that need per-user or per-tenant access control
agent clients that need to discover the right authorization server

Do not use this page as the primary model for stdio MCP servers. Stdio servers normally receive credentials from environment variables, local config, keychains, or the host application.

Protected Resource Metadata

A protected MCP server must advertise how clients can discover its authorization server.

The server can do this in two ways:

Return a WWW-Authenticate header with a resource_metadata URL on 401 Unauthorized.
Serve OAuth protected-resource metadata from a well-known URI.

Common well-known locations include:

https://example.com/.well-known/oauth-protected-resource
https://example.com/.well-known/oauth-protected-resource/public/mcp

The protected-resource metadata should include an authorization_servers field. The MCP client uses that metadata to discover the authorization server and then follows the normal OAuth flow.

Authorization Server Discovery

MCP authorization servers must support at least one discovery mechanism:

OAuth 2.0 Authorization Server Metadata
OpenID Connect Discovery 1.0

MCP clients must support both discovery mechanisms. This matters because different issuers publish metadata at different well-known paths.

For an issuer such as https://auth.example.com/tenant1, clients may need to try path-insertion and path-appending forms:

https://auth.example.com/.well-known/oauth-authorization-server/tenant1
https://auth.example.com/.well-known/openid-configuration/tenant1
https://auth.example.com/tenant1/.well-known/openid-configuration

Client Registration

MCP supports three client registration approaches:

Approach	Use when
Pre-registration	The client and authorization server already have a relationship.
OAuth Client ID Metadata Documents	The client and authorization server do not have a prior relationship, and the authorization server supports URL-formatted client IDs.
Dynamic client registration	The authorization server supports RFC 7591 and dynamic registration is appropriate.

When several options exist, clients should prefer pre-registered client details, then Client ID Metadata Documents when supported, then dynamic client registration as a fallback.

Client ID Metadata Documents

Client ID Metadata Documents are an OAuth client registration mechanism, not an MCP-specific /.well-known/mcp-client.json file.

The client uses an HTTPS URL as its client_id. That URL points to a JSON document containing OAuth client metadata. The document must include at least:

client_id
client_name
redirect_uris

Example:

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

Authorization servers advertise support with:

{
  "client_id_metadata_document_supported": true
}

The authorization server should fetch the metadata document, validate that the document's client_id exactly matches the URL, validate redirect URIs, and cache the document according to HTTP cache headers.

Clients may use private_key_jwt for token endpoint authentication when the metadata document provides the required JWKS configuration.

Token Use

MCP clients must send access tokens in the authorization header:

Authorization: Bearer <access-token>

Access tokens must not be placed in URI query strings.

The MCP client must include the OAuth Resource Indicators resource parameter during authorization and token requests. The resource must identify the MCP server the token is intended for.

MCP servers must validate that incoming access tokens were issued for their own resource. They must not accept tokens issued for another resource, and they must not pass through tokens they received from an MCP client.

Scope Challenges

When a request lacks sufficient scope, the server should use normal OAuth error handling:

401 Unauthorized when authorization is required or the token is invalid
403 Forbidden when the token is valid but lacks required scope
WWW-Authenticate with scope and resource_metadata when the client needs to request additional scope

Clients should treat a challenged scope as authoritative for satisfying that request. They should not assume it is always identical to the full scopes_supported list.