feat: fully support Basic Authorization header at token request by challenger71498 · Pull Request #1847 · modelcontextprotocol/python-sdk · GitHub

Summary

This PR implements OAuth client authentication by supporting HTTP Basic authentication as defined in RFC 6749 Section 2.3.1., especially when client_id is provided only from the header.

The key changes are:

Extract client credentials from Basic auth header first, before falling back to form data
Validate that the authentication method used matches what the client registered
Make client_id optional in token request body when using Basic auth (as the spec allows)

Previously, the code would first read client_id from the form body and then validate against the auth method. This caused issues when clients used Basic auth without including client_id in the request body, which is valid per the OAuth spec.

This PR resolves the issue OAuth TokenHandler should check Authorization header for client credentials #1315.

Motivation and Context

RFC 6749 Section 2.3.1 specifies that clients using client_secret_basic should send credentials via the Authorization header, and the client_id in the request body is optional in this case.
The previous implementation required client_id in the body even when using Basic auth, which was non-compliant with the spec.

How Has This Been Tested?

Unit Test

Added test for Basic auth working without client_id in request body
Added test for Basic auth taking precedence over form body client_id
Added test for refresh token flow without client_id in body
Updated existing tests to reflect new error messages when auth method mismatches

E2E Test

Tested with npx @modelcontextprotocol/inspector + OAuth provider mockup, and worked as expected.

Screenshots

Breaking Changes

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed no docs need to be updated

Additional context

OAuth TokenHandler Enhancement: Authorization Header Fallback Support #1316 tried to resolve the issue, but closed by Add client_secret_basic authentication support #1334.
- The approach of 1334 was right on track, but did not resolved the issue 1315 completely.

This test case only contains client_id and client_secret at Basic Authentication header, assuming that there is no client_id and client_secret at form data.

This data class contains creds plus auth method

Retrieve client_id from auth header or the body, then retrieve client via that client_id. After that, compare auth method.

`match` causes coverage error on python 3.10.

Note: the core extraction logic of client_id and client_secret is as same as before.

Note: test fails as same as before, only exception message has been changed, due to the auth method mismatch.

Note: the behaviour of the test has been changed. After the changes, basic auth takes precedence over form data, so even if there is a mismatch, the middleware retrieves the client_id from the header.

This behaviour is intended due to RFC 6749 Section 2.3.1:

Including the client credentials in the request-body using the two parameters is NOT RECOMMENDED and SHOULD be limited to clients unable to directly utilize the HTTP Basic authentication scheme (or other password-based HTTP authentication schemes).

If this is inappropriate, alternatives are:

behave AS-IS (throw mismatch exception)
disallow dup auth method
- throw exception which indicates that more than one authentication method was used.

@ochafik @pcarleton I saw you were involved in #1334 which added the client_secret_basic auth method, could you have a look at this PR as well?

I added my point of view on the issue this PR resolves in #1315 (comment) —* Including the realization that MCP is about OAuth 2.1 draft 13 and not RFC 6749, but that both standards seem to agree that client_id is not required for client_secret_basic

* human-crafted em dash

+1, hit this in production via FastMCP (OAuthProxy).

The bug compounds for FastMCP-based MCP servers because
OAuthProxy.register_client hard-codes token_endpoint_auth_method="none"
for DCR-registered clients (fastmcp/server/auth/oauth_proxy.py:1005 on
v2.14.7). So even though FastMCP advertises client_secret_basic in
token_endpoint_auth_methods_supported, the ClientAuthenticator middleware
never invokes the Basic-decoding path - and the
form_data.get("client_id") check at src/mcp/server/auth/middleware/client_auth.py:55
rejects the request with Missing client_id before any Basic header is
inspected.

Concrete repro against a vanilla FastMCP OAuthProxy deploy:

# Pure Basic auth - RFC 6749 §2.3.1 compliant
curl -sS -u "$CID:$CSEC" \
  -d 'grant_type=authorization_code&code=test&redirect_uri=...' \
  http://server/token
# → 401 {"error":"invalid_client","error_description":"Missing client_id"}

# Same creds in POST body
curl -sS \
  -d "grant_type=authorization_code&code=test&client_id=$CID&client_secret=$CSEC&redirect_uri=..." \
  http://server/token
# → 400 (reaches code_verifier validation; client_id was parsed)

Same handler, same input, different carrier. The diff in this PR fixes the
right layer (client_auth.py), so the FastMCP case is fixed transitively.

Spec-compliant @ai-sdk/mcp clients default to client_secret_basic when
the server advertises both - they're the most affected. Happy to add a
regression test covering the Basic-only path if it helps land this.

challenger71498 added 15 commits January 11, 2026 15:42

test: add case for token request with basic auth header

38cbae1

This test case only contains client_id and client_secret at Basic Authentication header, assuming that there is no client_id and client_secret at form data.

test: add case for basic auth only

185d2ad

fix: resolve client_id from client_info

f3d84f7

feat: add ClientCredentials

cc4a70f

This data class contains creds plus auth method

feat: seperate credential extraction into a method

ea1f8c7

fix: retrieve client_id first then compare auth method

85ce44b

Retrieve client_id from auth header or the body, then retrieve client via that client_id. After that, compare auth method.

test: update unit test

5788692

test: rm duplicated test

c7e46f3

chore: address ruff

4f789a7

test: add case for refresh token

368c2a8

fix: apply changes to RefreshTokenRequest

c6639a6

refactor: rm redundant str casting

b2641a5

chore: fix coverage

64b4446

chore: address ruff

7d59fa7

refactor: use if rather than match

d284f6f

`match` causes coverage error on python 3.10.

challenger71498 commented Jan 11, 2026

View reviewed changes

joar mentioned this pull request Mar 26, 2026

OAuth TokenHandler should check Authorization header for client credentials #1315

Open

benmiller-SC mentioned this pull request Jul 21, 2026

OAuth client sends client_id in token body under client_secret_basic (strict servers reject as multiple auth methods) #3138

Open

2 tasks

                       # RFC 6749: authentication failures return "invalid_client"
                       assert error_response["error"] == "invalid_client"
-                      assert "Missing or invalid Basic authentication" in error_response["error_description"]
+                      assert "Expected client_secret_basic authentication method" in error_response["error_description"]

feat: fully support Basic Authorization header at token request by challenger71498 · Pull Request #1847 · modelcontextprotocol/python-sdk · GitHub

Uh oh!

feat: fully support Basic Authorization header at token request - #1847

feat: fully support Basic Authorization header at token request#1847
challenger71498 wants to merge 15 commits into
modelcontextprotocol:mainfrom
challenger71498:feat/header-based-oauth

challenger71498 commented Jan 11, 2026 •
edited
Loading

Uh oh!

Uh oh!

challenger71498 Jan 11, 2026

Uh oh!

challenger71498 Jan 11, 2026 •
edited
Loading

Uh oh!

Uh oh!

challenger71498 Jan 11, 2026 •
edited
Loading

Uh oh!

Uh oh!

challenger71498 Jan 11, 2026 •
edited
Loading

Uh oh!

Uh oh!

joar commented Mar 26, 2026

Uh oh!

MesoX commented May 24, 2026 •
edited
Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		return client

		async def _get_credentials(self, request: Request) -> ClientCredentials:

                   @pytest.mark.anyio
-                  async def test_wrong_auth_method_without_valid_credentials_fails(
+                  async def test_wrong_auth_method_fails(

                   @pytest.mark.anyio
-                  async def test_basic_auth_client_id_mismatch_fails(
+                  async def test_basic_auth_takes_precedence(

feat: fully support Basic Authorization header at token request by challenger71498 · Pull Request #1847 · modelcontextprotocol/python-sdk · GitHub

Uh oh!

feat: fully support Basic Authorization header at token request - #1847

Conversation

challenger71498 commented Jan 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation and Context

How Has This Been Tested?

Unit Test

E2E Test

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

challenger71498 Jan 11, 2026

Choose a reason for hiding this comment

Uh oh!

challenger71498 Jan 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

challenger71498 Jan 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

challenger71498 Jan 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joar commented Mar 26, 2026

Uh oh!

MesoX commented May 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

challenger71498 commented Jan 11, 2026 •
edited
Loading

challenger71498 Jan 11, 2026 •
edited
Loading

challenger71498 Jan 11, 2026 •
edited
Loading

challenger71498 Jan 11, 2026 •
edited
Loading

MesoX commented May 24, 2026 •
edited
Loading