[wyattjoh]

What

The Express and Hono adapters now send the same WWW-Authenticate challenges as the Clerk MCP server guide. mcpAuthClerk({ resourceUrl, requiredScopes }) also checks the token's audience, so the guide's inline auth code can be replaced with it.

Why

The guide writes its own /mcp auth middleware because the adapters can't do the job. Their resource_metadata value is unquoted, which RFC 9110 doesn't allow. A rejected token gets a 401 with no challenge at all, and a token missing scopes can't get a 403. mcpAuthClerk never checks the audience, so an OAuth access token issued to any other app on the same Clerk instance is accepted. In Express, a bare Authorization: Bearer header hangs the request.

How

• Express and Hono share one response rule in an internal bearer-auth.ts module, so the two can't drift apart again:

  Request	Status	Challenge
  No header, or a malformed one	401	Bearer resource_metadata="…"
  Token rejected	401	adds error="invalid_token" (RFC 6750 §3)
  Token missing requiredScopes	403	adds error="insufficient_scope", scope="…" (RFC 6750 §3.1)

• Values in the challenge are quoted strings (RFC 9110 Appendix A), and resource_metadata follows RFC 9728 §5.1.

• The 403 scope lists the token's granted scopes followed by the missing ones, as requireAdditionalScopes does, so re-authorizing doesn't drop access the token already had. The guide lists only the required scopes; this is a deliberate superset.

• Breaking: mcpAuthClerk is now a factory that requires resourceUrl and passes it to authenticateRequest as the audience. Code that still passes the bare mcpAuthClerk to a route gets a Clerk error: explaining the new call form instead of hanging.

• Breaking: the peer ranges now start at @clerk/express 2.1.70 and @clerk/hono 0.1.80. Before those versions, a JWT without an aud claim and an opaque token both pass the audience check. The dev dependencies are pinned to these minimums, so the tests run against the oldest versions we support.

• mcpAuth takes optional resourceUrl and requiredScopes. resourceUrl sets resource_metadata instead of building it from the request, which can be wrong behind a proxy.

• Express mcpAuth is now synchronous, rejects schemes other than Bearer, and leaves the query string out of resource_metadata.

• In the Next.js adapter, the protected resource metadata resource now includes the route path, as it already does in Express and Hono. Its challenge still comes from mcp-handler's withMcpAuth.

Follow-ups

• Before the guide switches to mcpAuthClerk, test the audience check against a real Clerk instance: a token issued for another resource or OAuth application must get a 401. The tests here use a mocked Clerk client.
• Update the Clerk MCP guide to use mcpAuthClerk once this is released.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts