Sign agents in to your app with a one-time link, Beta

When an agent uses a browser for your user and reaches your app's sign-in page, it usually stops there, or asks the user for a password. A create_browser_session tool on your MCP server lets the agent get a one-time link instead. The link opens your app already signed in as the user that the MCP access token belongs to.

You add the tool with @clerk/mcp-tools⁠. It creates the link with Agent Tasks and takes the user from the verified access token, never from the tool's input. The agent can set only the path in your app and a short task description.

This guide adds the tool to the MCP server from Build an MCP server. Follow that guide first. The tool relies on its verifyMcpToken(), which checks the token's audience and returns the result of verifyClerkToken(). Without the audience check, any OAuth access token your instance issued, to any OAuth application, could create a link.

npm install @clerk/mcp-tools@latest

pnpm add @clerk/mcp-tools@latest

yarn add @clerk/mcp-tools@latest

bun add @clerk/mcp-tools@latest

export const BROWSER_SESSION_SCOPES = ['browser_session']

import {
  BROWSER_SESSION_SCOPES,
  getUserProfile,
  MCP_RESOURCE_URL,
  REQUIRED_SCOPES,
  RESOURCE_METADATA_URL,
  verifyMcpToken,
} from './lib/mcp-auth.ts'

// The rest of your code...

app.get(
  '/.well-known/oauth-protected-resource/mcp',
  protectedResourceHandlerClerk({
    resource: MCP_RESOURCE_URL,
    scopes_supported: [...REQUIRED_SCOPES, ...BROWSER_SESSION_SCOPES],
  }),
)

import {
  authServerMetadataHandlerClerk,
  protectedResourceHandlerClerk,
  streamableHttpHandler,
} from '@clerk/mcp-tools/express'
import {
  browserSessionInstructions,
  createBrowserSessionTool,
} from '@clerk/mcp-tools/create-browser-session'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import {
  BROWSER_SESSION_SCOPES,
  getUserProfile,
  MCP_RESOURCE_URL,
  REQUIRED_SCOPES,
  RESOURCE_METADATA_URL,
  verifyMcpToken,
} from './lib/mcp-auth.ts'

const APP_URL = 'http://localhost:3000/'

// Created once, so a bad configuration fails at startup instead of on every request
const browserSessionTool = createBrowserSessionTool({
  secretKey: process.env.CLERK_SECRET_KEY!,
  destinationUrl: APP_URL,
  requiredScopes: BROWSER_SESSION_SCOPES,
})

function createServer() {
  const server = new McpServer(
    { name: 'profile-server', version: '1.0.0' },
    { instructions: browserSessionInstructions(APP_URL) },
  )
  server.registerTool(...browserSessionTool)

  // Your other tools...

  return server
}

// The rest of your code...

What the session can do

By default, the link starts a restricted session. The session can read data and refresh its own session token. Clerk's Frontend API refuses every other write from it, including:

• Session touch requests, which update the session's last active time
• Sign-in, sign-up, and sign-out
• A switch to another session or Organization
• Changes to the user's own profile and Organizations
• Reverification, and OAuth consent and approval

The agent controls the browser, so these limits keep it from approving its own OAuth grant or changing the user's credentials.

Clerk also refuses JWT template and Firebase tokens, so getToken({ template }) fails in a restricted session.

Your app's backend sees an ordinary signed-in session, and Clerk doesn't limit what your own API lets it do. To treat agent sessions differently in your backend, check for the agt claim in the session's sessionClaims.

If Clerk doesn't confirm the restriction, the tool tries to revoke the link, returns no link, and fails with the restricted_not_applied error code.

To start an ordinary session instead, pass restricted: false to createBrowserSessionTool().

Security and limits

• The link is a credential: anyone who has it before it's used or expires can sign in as the user. The tool never includes it in errors or logs, but the tool result contains it so that the agent can open it. Don't log tool results, and treat MCP client and gateway logs of tool results as credentials.
• Each link works once and expires after 1 hour. The session it starts lasts up to 30 minutes by default. Set sessionMaxDurationInSeconds to change that.
• The agent can pass a path, such as /settings, with an optional query and hash. It replaces the path of destinationUrl, and the tool refuses any path that would leave your app.
• The session starts in the user's last active Organization if they're still a member, and otherwise in their personal workspace. A restricted session can't start in the personal workspace when your instance has Membership required turned on. In that case, the tool fails with the organization_rejected error code. A restricted session can't switch to another Organization.