Request more scopes with step-up authorization

When a client connects to your MCP server, the user approves a set of scopes. With step-up authorization, that first grant stays small, and the server asks for more scopes only when the agent calls a tool that needs them:

1. The agent calls a tool, such as whoami, with an access token that lacks the tool's scope.
2. Before the tool runs, your server answers 403 Forbidden with a challenge: a WWW-Authenticate: Bearer error="insufficient_scope", scope="..." header that names the scopes to request.
3. The MCP client sends the user through Clerk's OAuth consent screen again, this time for the scopes in the challenge.
4. The client retries the tool call with the new access token.

The MCP TypeScript SDK (@modelcontextprotocol/server) sends this challenge for you when you set the scopeChallenge option of registerTool(). The requireAdditionalScopes() helper from @clerk/mcp-tools⁠ builds that option from the scopes a tool needs.

This guide assumes that you've completed Build an MCP server. It changes that server so that clients connect with only the profile scope, the baseline every request needs. Its get_clerk_user_data tool stops returning the email address, and a new whoami tool returns the user's ID and primary email. email becomes the step-up scope: the server asks clients for it the first time they call whoami.

Clients handle the challenge differently, so check your client's documentation. For example, Claude Code reports the missing scopes and asks the user to run /mcp, which opens the consent screen for those scopes. Clients without step-up support report a failed request and ask for the same baseline scopes when they reconnect, so their users can't use the tool unless the client requests the step-up scope when it connects.

npm install @clerk/mcp-tools@latest @modelcontextprotocol/server@latest mcp-handler@latest

pnpm add @clerk/mcp-tools@latest @modelcontextprotocol/server@latest mcp-handler@latest

yarn add @clerk/mcp-tools@latest @modelcontextprotocol/server@latest mcp-handler@latest

bun add @clerk/mcp-tools@latest @modelcontextprotocol/server@latest mcp-handler@latest

  // ...
- export const REQUIRED_SCOPES = ['profile', 'email']
+ export const REQUIRED_SCOPES = ['profile']
  
  // ...
  
  export async function getUserProfile(userId: string) {
    const user = await clerkClient.users.getUser(userId)
    return {
      id: user.id,
      firstName: user.firstName,
      lastName: user.lastName,
      imageUrl: user.imageUrl,
-     email:
-       user.emailAddresses.find((address) => address.id === user.primaryEmailAddressId)
-         ?.emailAddress ?? null,
    }
  }
  
+ export async function getWhoami(userId: string) {
+   const user = await clerkClient.users.getUser(userId)
+   return {
+     id: user.id,
+     email:
+       user.emailAddresses.find((address) => address.id === user.primaryEmailAddressId)
+         ?.emailAddress ?? null,
+   }
+ }

+ import { requireAdditionalScopes } from '@clerk/mcp-tools/next'
  import { createMcpHandler, withMcpAuth } from 'mcp-handler'
  import {
    getUserProfile,
+   getWhoami,
    MCP_RESOURCE_URL,
    REQUIRED_SCOPES,
    verifyMcpToken,
  } from '../../lib/mcp-auth'
  
  const handler = createMcpHandler((server) => {
    server.registerTool(
      'get_clerk_user_data',
-     { description: 'Gets the authorized user’s profile and primary email' },
+     { description: 'Gets the authorized user’s profile' },
      async (ctx) => {
        // ...
      },
    )
  
+   server.registerTool(
+     'whoami',
+     {
+       description: 'Gets the authorized user’s ID and primary email. Needs the email scope.',
+       scopeChallenge: requireAdditionalScopes('email'),
+     },
+     async (ctx) => {
+       const userId = ctx.http?.authInfo?.extra?.userId
+       if (typeof userId !== 'string') throw new Error('Missing authenticated user')
+       return {
+         content: [{ type: 'text', text: JSON.stringify(await getWhoami(userId)) }],
+       }
+     },
+   )
  })
  
  const authHandler = withMcpAuth(handler, (request) => verifyMcpToken(request), {
    required: true,
    requiredScopes: REQUIRED_SCOPES,
    // mcp-handler appends resourceMetadataPath to this origin for the WWW-Authenticate challenge
    resourceUrl: new URL(MCP_RESOURCE_URL).origin,
    resourceMetadataPath: '/.well-known/oauth-protected-resource/mcp',
  })
  
  export { authHandler as GET, authHandler as POST }

Best practices

Follow these rules for every tool that uses scopeChallenge.

Challenge for the full scope set

The scope in the challenge is the complete set the client should request, including the scopes the token already has. Some clients request exactly the challenged scopes, and the new token replaces the old one. A challenge for only email produces a token without profile, and every other tool then fails or challenges again.

requireAdditionalScopes() requires the tool's scopes in addition to the ones the token already has, so it challenges for the granted scopes plus the missing ones. The SDK's own requireScopes() helper challenges for only the scopes you list, so if you use it, list every scope the token should keep.

Keep step-up scopes out of the baseline

Add the step-up scope only to the tool's scopeChallenge. Anywhere else, step-up doesn't work as intended:

• Route checks, such as the requiredScopes of withMcpAuth() or the check in the Express route, run on every request, including initialize and tools/list. A step-up scope there rejects every token without it.
• scopes_supported in your protected resource metadata guides what MCP clients request when they first connect, unless the 401 challenge names scopes of its own. Keep it to the baseline, as in the build guide. It doesn't limit what a token can get, so a client can still request step-up scopes up front.

Limitations

scopeChallenge applies only to certain requests, so check these limits before you rely on it.

When the SDK sends the challenge

The SDK sends the challenge only when:

• The server runs @modelcontextprotocol/server 2.1 or later. Tools behind the streamableHttpHandler() adapters in @clerk/mcp-tools/express and @clerk/mcp-tools/hono run SDK 1.x and must check their scopes themselves.
• The request comes over HTTP, through createMcpHandler() or the Streamable HTTP transport. Over stdio (local servers), the tool runs without the challenge.
• The request carries auth info. requireAdditionalScopes() and requireScopes() leave unauthenticated requests to your authentication check.

How the challenge behaves

• The SDK checks tools/call, resources/read, and prompts/get requests for enabled tools, resources, and prompts. registerResource() and registerPrompt() accept the same scopeChallenge option.
• The challenge runs before the SDK validates the tool's arguments.
• tools/list still includes the tool for tokens that lack its scope. Mention the step-up scope in the tool's description so agents know to expect another consent screen.
• If a scopeChallenge function throws, the SDK answers 500 Internal Server Error. requireAdditionalScopes() validates its scopes when you call it. It throws a Clerk error: at startup if you pass no scopes, an empty string, or a scope with a space, quote, backslash, control character, or non-ASCII character.