oauth-client-credentials.mdx

Protocol Revision: draft

Introduction

Purpose and Scope

This extension defines OAuth 2.1 Client Credentials flow support for the Model Context Protocol, enabling machine-to-machine authentication without user interaction. This extension builds upon the baseline authorization requirements defined in the main Authorization specification.

Extension Requirements

This extension is OPTIONAL for MCP implementations. When adopted:

• Implementations MUST conform to all requirements specified in this extension
• Implementations MUST also conform to the baseline authorization requirements
• This extension is specifically designed for HTTP-based transports

Standards Compliance

This extension is based on the following established specifications:

• OAuth 2.1 IETF DRAFT (draft-ietf-oauth-v2-1-13)
• OAuth 2.0 Authorization Server Metadata (RFC8414)
• OAuth 2.0 Protected Resource Metadata (RFC9728)
• JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants (RFC7523)

Client Credentials Flow

Overview

The Client Credentials flow enables machine-to-machine authentication without user interaction. This flow requires pre-registered client credentials, which are typically established out-of-band through administrative channels. Dynamic Client Registration is not used in this flow.

Client Authentication Methods

Clients MUST authenticate using one of these methods:

• JWT Authentication (RECOMMENDED)
  • Clients use JWT Authentication as defined in RFC 7523 Section 2.2.
• Client Secret
  • Clients use a Client Secret transmitted in the request content as defined in OAuth 2.1 Section 2.4.1

Server Metadata Requirements

When supporting the client credentials flow, Authorization Server metadata MUST include the following fields:

• token_endpoint_auth_methods_supported: MUST include at least one of:
  • "private_key_jwt"
  • "client_secret_basic"
• token_endpoint_auth_signing_alg_values_supported: Required when supporting JWT authentication

Flow Steps

The complete Client Credentials flow proceeds as follows:

sequenceDiagram
    participant C as Client
    participant M as MCP Server (Resource Server)
    participant A as Authorization Server

    C->>M: MCP request without token
    M->>C: HTTP 401 Unauthorized with WWW-Authenticate header
    Note over C: Extract resource_metadata URL from WWW-Authenticate

    C->>M: Request Protected Resource Metadata
    M->>C: Return metadata

    Note over C: Parse metadata and extract authorization server(s)<br/>Client determines AS to use

    C->>A: GET Authorization server metadata endpoint
    Note over C,A: Try OAuth 2.0 and OpenID Connect<br/>discovery endpoints in priority order
    A-->>C: Authorization server metadata

    Note over C: Prepare client authentication
    alt JWT Authentication (RECOMMENDED)
        Note over C: Generate signed JWT assertion
        C->>A: POST /token with client_assertion
    else Client Secret Authentication
        Note over C: Use client_id and client_secret
        C->>A: POST /token with client credentials
    end
    A->>C: Access token
    C->>M: MCP request with access token
    M-->>C: MCP response
    Note over C,M: MCP communication continues with valid token

Examples

The following examples illustrate both client authentication methods:

JWT Authentication Example

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0.
     eyJpc3Mi[...omitted for brevity...].
     cC4hiUPo[...omitted for brevity...]
&resource=https%3A%2F%2Fmcp.example.com
&scope=mcp%3Aread

Note: The client_id parameter is omitted from the request body as RFC 7523 Section 3 specifies that client identification is conveyed through the sub claim within the JWT assertion.

Client Secret Authentication Example

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=s6BhdRkqt3
&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw
&resource=https%3A%2F%2Fmcp.example.com
&scope=mcp%3Aread

Security Considerations

Implementations adopting this extension MUST follow OAuth 2.1 security best practices as laid out in OAuth 2.1 Section 7. "Security Considerations", with particular attention to:

• Client authentication security
• Token storage and handling
• Communication security requirements
• Client credential protection

For detailed security guidance specific to client credentials flows, refer to RFC 7523 Section 5 "Security Considerations".