MCP Authentication

Auth Model

Every tool call to the Lev MCP server is validated against an Auth0-issued RS256 JWT. When you install the server via Claude Code, Claude Desktop, or Cursor, OAuth is already wired up — you sign in once, and the client handles tokens from there.

The OAuth Flow

The first tool call triggers a standards-compliant OAuth 2.0 authorization-code flow. Clients discover the server's authorization metadata, not the other way around.

1. Discovery. The client fetches <mcp-server-url>/.well-known/oauth-authorization-server to learn the authorize, token, and JWKS endpoints.
2. Authorize. The client opens the browser to Auth0's hosted login page with a PKCE challenge and a redirect URI that points back at the client.
3. Callback. After the user signs in, Auth0 redirects back with an authorization code.
4. Token exchange. The client exchanges the code for an RS256-signed access token (a JWT) and a refresh token.
5. Tool calls. Every subsequent MCP request includes Authorization: Bearer <jwt>. The server validates the signature, expiry, audience, and issuer against the JWKS it discovered from Auth0.
6. Refresh. When the access token expires, the client silently refreshes it using the refresh token. No user action required.

Scopes and Permissions

The OAuth flow requests two scopes from Auth0:

The scopes above are what the server asks Auth0 for. What tools you can actually call depends on your Lev account permissions. The MCP server never elevates privileges — every call downstream to lev-backend is scoped to your live role.

That means:

• A 403 on a tool means your Lev user does not have access to the resource, not that the MCP server misrouted the call.
• A role change in Lev takes effect on the next tool call. The server does not cache authorization decisions.

To see what a given session actually has access to, call get_my_profile. It returns your user record, active account, available accounts, subscription status, and any platform-level scopes granted to the session.

Headers Sent to Lev

Every call the MCP server makes to lev-backend carries a predictable header set. You do not need to set these — they are listed so you can spot them in traces and logs.

Switching Accounts

Some Lev users belong to more than one account — a brokerage and a lender, for example. The MCP server supports switching between them without ending the session.

How to switch

Ask the client in plain language, for example: "Switch my Lev account to Broker Magicians." The client will call the switch_account tool with the name or slug, and subsequent tool calls will scope to that account via the X-Active-Account header.

Listing available accounts

list_available_accounts returns every account you can switch to. Use this when you are not sure of the exact slug.