[manovotny]

Summary

Two gaps from reviewing clerk/clerk#3786. The README said a 401 usually names no scope, which is wrong for Next.js servers on mcp-handler. The step-up e2e test also never gave the client a refresh token, so it missed the case where the MCP SDK 1.x client can't step up.

Changes

• README: a 401 names scopes only when the server adds them, as mcp-handler's withMcpAuth does from its requiredScopes. Otherwise, scopes_supported is what a client requests on first connection.
• test/step-up.test.ts: adds a client holding a refresh token. The SDK 1.x client refreshes instead of redirecting, gets the same scopes back, and throws Server returned 403 after trying upscoping, so the user never reaches consent. Clerk issues refresh tokens by default, so real clients on 1.x land here.
• Empty changeset: no package changes.

The new test pins current SDK behavior. It fails if a 1.x backport lands, and that's the cue to flip it to expect the redirect.

References

• clerk/clerk#3786
• feat(server): export requireAdditionalScopes for MCP SDK 2.1+ step-up #46
• Step-up authorization (403 insufficient_scope) dead-ends with SdkHttpError when a refresh_token is present modelcontextprotocol/typescript-sdk#2255

🤖 Generated with Claude Code

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

The README clarifies when a 401 challenge names scopes and what clients usually request when no scopes are named. The end-to-end test records token requests and adds coverage for an SDK 1.x client that refreshes its token but does not obtain additional scopes. The changeset adds empty frontmatter with no release metadata.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• clerk/mcp-tools#46: Adds the step-up helper and end-to-end test that this change extends.
• clerk/mcp-tools#44: Adds insufficient-scope challenges that trigger client step-up.
• clerk/mcp-tools#43: Adds tool scope challenges and tests client redirects for under-scoped tokens.

Suggested reviewers: brkalow

Merge Risk: Low · up to 7ce3a

This PR changes documentation and tests only. The README guidance may mislead integrators whose clients use SDK 1.x with refresh tokens, and the new test does not fully prove that the retry uses the refreshed token. Both are worth fixing, but neither affects shipped runtime behavior.

- [ ] Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

[brkalow]

❤️