`v2`: fix simpleStreamableHttp auth example for inspector connect flow #1427

KKonstantinov · 2026-01-28T07:22:38Z

This PR fixes OAuth authentication flow issues in the better-auth example implementation, enabling compatibility with MCP Inspector in both Direct and Proxy modes.

Thanks @cliffhall for reporting this!

Motivation and Context

The better-auth OAuth implementation in the examples had several issues preventing it from working correctly with MCP clients:

Missing CORS headers - Browser-based clients couldn't fetch OAuth metadata or make authenticated requests
Wrong metadata path - Protected resource metadata was served at /.well-known/oauth-protected-resource instead of RFC 9728-compliant /.well-known/oauth-protected-resource/mcp (per MCP Authorization Spec)
Incompatible WWW-Authenticate header format - The header was missing error and error_description fields that MCP Inspector's proxy expects

How Has This Been Tested?

Tested with MCP Inspector in Direct mode - OAuth flow completes successfully
Tested with MCP Inspector in Proxy mode - OAuth flow completes successfully
Verified OAuth metadata endpoints return correct CORS headers
Verified protected resource metadata is served at correct RFC 9728 path
Verified WWW-Authenticate header format matches v1.x implementation

Breaking Changes

No breaking changes. The createProtectedResourceMetadataRouter() function now accepts an optional resourcePath parameter (defaults to '/mcp'), but existing calls without the parameter will continue to work.

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

Additional context

Key changes:

CORS Configuration:

Added cors middleware to MCP server with exposed headers for WWW-Authenticate and Mcp-Session-Id
Added cors middleware to auth server for all OAuth endpoints
Added explicit OPTIONS handlers for metadata endpoints

RFC 9728 Compliance:

createProtectedResourceMetadataRouter(resourcePath) now serves metadata at the path-specific URL (e.g., /.well-known/oauth-protected-resource/mcp)
Per MCP Authorization Specification: MCP servers MUST implement RFC 9728 and serve metadata at the path of the server's MCP endpoint

WWW-Authenticate Header:

Updated format to match v1.x: Bearer error="invalid_token", error_description="...", resource_metadata="..."
This is required for MCP Inspector's proxy mode which uses the v1.x client SDK

Debug Logging:

Added --dangerous-logging-enabled CLI flag to enable verbose better-auth request/response logging
Disabled by default to avoid logging sensitive information (tokens, cookies)

TypeScript Configuration:

Disabled declaration and declarationMap in examples/shared/tsconfig.json to avoid TS4058 error with better-auth's internal MCPOptions type - it's not exported out of the better-auth package (TBD: Raise an issue on better-auth). Since we are not building and publishing this package, it should be fine to disable these for the example package.

Dependency Upgrades:

Upgraded better-auth to latest version
Upgraded better-sqlite3 to latest version

changeset-bot · 2026-01-28T07:22:42Z

⚠️ No Changeset found

Latest commit: b24d7e7

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes changesets to release 1 package

Name	Type
@modelcontextprotocol/client	Patch

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

pkg-pr-new · 2026-01-28T07:27:05Z

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@1427

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@1427

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@1427

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@1427

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@1427

commit: b24d7e7

cliffhall

A couple of extra headers the MCP client needs to see. And explicit "*" origin.

examples/server/src/simpleStreamableHttp.ts

examples/shared/src/authServer.ts

Co-authored-by: Cliff Hall <[email protected]>

pcarleton

These changes look good to me!

wondering if an optional conformance test for "Browser client compatibility" would be helpful to help highlight when servers don't have this set

cliffhall

Woops. Left off a comma in the suggestion

cliffhall · 2026-01-28T15:41:59Z

examples/shared/src/authServer.ts

-    });
+    authApp.use(
+        cors({
+            exposedHeaders: ['WWW-Authenticate']


Suggested change

exposedHeaders: ['WWW-Authenticate']

exposedHeaders: ['WWW-Authenticate'],

KKonstantinov · 2026-01-28T16:03:06Z

These changes look good to me!

wondering if an optional conformance test for "Browser client compatibility" would be helpful to help highlight when servers don't have this set

@pcarleton I believe so, yes! It'll be very helpful to nail these scenarios down, so they're kind of set in stone

…KKonstantinov/typescript-sdk into feature/v2-example-auth-fixes-inspector

fix simpleStreamableHttp auth example for inspector connect flow

e60ea4c

KKonstantinov requested a review from a team as a code owner January 28, 2026 07:22

cliffhall suggested changes Jan 28, 2026

View reviewed changes

examples/server/src/simpleStreamableHttp.ts Outdated Show resolved Hide resolved

examples/shared/src/authServer.ts Outdated Show resolved Hide resolved

felixweinberger requested a review from pcarleton January 28, 2026 15:35

Apply suggestions from code review

8e54d04

Co-authored-by: Cliff Hall <[email protected]>

pcarleton previously approved these changes Jan 28, 2026

View reviewed changes

cliffhall suggested changes Jan 28, 2026

View reviewed changes

KKonstantinov added 3 commits January 28, 2026 18:05

add protected resource metadata URL console log

063bb40

Merge branch 'feature/v2-example-auth-fixes-inspector' of github.com:…

f6fd1db

…KKonstantinov/typescript-sdk into feature/v2-example-auth-fixes-inspector

merge commit

b24d7e7

KKonstantinov dismissed pcarleton’s stale review via b24d7e7 January 28, 2026 17:04

KKonstantinov merged commit b0ef89f into modelcontextprotocol:main Jan 28, 2026
10 checks passed

cliffhall mentioned this pull request Jan 28, 2026

Fix connection error when using the Inspector with the MCP server with authentication enabled jacopoc/mcp-server-for-apache-ofbiz#70

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

`v2`: fix simpleStreamableHttp auth example for inspector connect flow #1427

`v2`: fix simpleStreamableHttp auth example for inspector connect flow #1427

KKonstantinov commented Jan 28, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Jan 28, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Jan 28, 2026 •

edited

Loading

Uh oh!

cliffhall left a comment

Uh oh!

Uh oh!

Uh oh!

pcarleton left a comment

Uh oh!

cliffhall left a comment

Uh oh!

cliffhall Jan 28, 2026

Uh oh!

KKonstantinov commented Jan 28, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	exposedHeaders: ['WWW-Authenticate']
	exposedHeaders: ['WWW-Authenticate'],

v2: fix simpleStreamableHttp auth example for inspector connect flow #1427

v2: fix simpleStreamableHttp auth example for inspector connect flow #1427

Conversation

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

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Key changes:

Uh oh!

changeset-bot bot commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

pkg-pr-new bot commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cliffhall left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

pcarleton left a comment

Choose a reason for hiding this comment

Uh oh!

cliffhall left a comment

Choose a reason for hiding this comment

Uh oh!

cliffhall Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

`v2`: fix simpleStreamableHttp auth example for inspector connect flow #1427

`v2`: fix simpleStreamableHttp auth example for inspector connect flow #1427

KKonstantinov commented Jan 28, 2026 •

edited

Loading

changeset-bot bot commented Jan 28, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 28, 2026 •

edited

Loading

KKonstantinov commented Jan 28, 2026 •

edited

Loading