Skip to content

SEP-1046 and SEP-1502: Support client credentials flow via new MCP Extension mechanism #1047

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
D-McAdams wants to merge 1 commit into from
Closed

SEP-1046 and SEP-1502: Support client credentials flow via new MCP Extension mechanism #1047

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions docs/specification/draft/extensions/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
---
title: Extensions
---

<div id="enable-section-numbers" />

<Info>**Protocol Revision**: draft</Info>

## Introduction

### Purpose and Scope

The Model Context Protocol specification defines baseline requirements for core
functionality. Extensions provide additional capabilities that implementations
may adopt to support specific use cases beyond the baseline requirements.

### Extension Design Principles

To ensure extensions integrate seamlessly with the core protocol while maintaining
flexibility for diverse implementation needs, all extensions must adhere to the
following architectural principles:

1. **Independence**: Extensions MUST provide complete specifications that can be
implemented independently without dependencies on other extensions.
2. **Composability**: Extensions MUST be modular such that multiple extensions
can be composed together within a single implementation without conflicts.

### Extension Conformance Model

Implementations **MAY** choose to adopt one or more extensions based on their
specific requirements. Once an extension is adopted, implementations **MUST**
conform to all requirements specified in that extension.

### Extension Governance

Extensions defined within this directory follow established MCP governance and
review processes.

Implementations **MAY** define additional extensions outside of this
specification. Such extensions are not subject to MCP governance processes. The
design, maintenance, and interoperability of external extensions are the
responsibility of their respective communities.

### Available Extensions

The following extensions are currently available:

- **[OAuth Client Credentials Extension](./specifications/auth-client-credentials.mdx)** -
Enables machine-to-machine authentication without user interaction using OAuth
2.1 Client Credentials flow
163 changes: 163 additions & 0 deletions docs/specification/draft/extensions/specifications/auth-client-credentials.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
---
title: OAuth Client Credentials Extension
---

<div id="enable-section-numbers" />

<Info>**Protocol Revision**: draft</Info>

## 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](../basic/authorization.mdx).

### 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](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 Protected Resource Metadata
([RFC9728](https://datatracker.ietf.org/doc/html/rfc9728))
- JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and
Authorization Grants
([RFC7523](https://datatracker.ietf.org/doc/html/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](https://datatracker.ietf.org/doc/html/rfc7523#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](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#name-client-secret)

### 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:

```mermaid
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](https://datatracker.ietf.org/doc/html/rfc7523#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"](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13#name-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"](https://datatracker.ietf.org/doc/html/rfc7523#section-5).