Authentication helpers

View the source code for this module on GitHub: https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/server/oauth/index.ts

These helpers read the authentication context that the OAuth bearer middleware attaches to each request, and gate tools or custom routes by OAuth scope or permission. They are standalone functions plus the related types they accept and return. They all import from mcp-use/server. When an OAuth provider or proxy is configured on the server (the oauth option of MCPServer), the bearer middleware verifies the token, builds an AuthInfo object, and attaches it to the request. Inside a tool callback the same object is also exposed directly as ctx.auth. The functions below operate on the Hono Context, so they work both in middleware and in tool callbacks that receive the request context.

import {
  getAuth,
  hasScope,
  hasAnyScope,
  requireScope,
  requireAnyScope,
  jwksVerifier,
} from "mcp-use/server";
import type {
  AuthInfo,
  UserInfo,
  VerifyToken,
  JwksVerifierConfig,
  OAuthProvider,
} from "mcp-use/server";

Functions

getAuth

Reads the authentication info the bearer middleware stored on the request and returns it as an AuthInfo.

import { getAuth } from "mcp-use/server";

Reads the authentication info that the bearer middleware stored on the request and returns it as an AuthInfo object. Works in both middleware and tool callbacks (the tool requestContext is a Hono Context). The value is read from the context variable auth (set by the middleware after a token is verified). Inside a tool callback you can read the same object directly as ctx.auth, so getAuth is mainly kept for compatibility with code that passes the raw context around. If no token was verified for the request (no provider configured, or the route is unauthenticated), the auth variable is unset and the return value is undefined at runtime even though the static type is AuthInfo.

import { getAuth } from "mcp-use/server";

Parameters

Context
required
Hono context, from middleware or from a tool’s requestContext parameter.

Returns

AuthInfo

Signature

function getAuth(context: Context): AuthInfo

hasScope

Returns true only if the authenticated user has every scope (or permission) in needed (logical AND).

import { hasScope } from "mcp-use/server";

Returns true only if the authenticated user has every scope (or permission) in needed. Both the OAuth scopes array and the Auth0 style permissions array are checked, so a value present in either one counts as granted. A single string is treated as a one element list. When needed is an array, ALL entries must be present (logical AND). Use this inside a tool callback to check access and return your own error result. It calls getAuth internally, so a request with no verified auth will throw when it tries to destructure the missing AuthInfo.

import { hasScope } from "mcp-use/server";

Parameters

Context
required
Hono context, typically the tool’s requestContext parameter.

string | string[]
required
A single scope/permission, or an array of scopes/permissions that must ALL be present.

Returns

boolean

Signature

function hasScope(context: Context, needed: string | string[]): boolean

hasAnyScope

Returns true if the authenticated user has at least ONE of the scopes (or permissions) in needed (logical OR).

import { hasAnyScope } from "mcp-use/server";

Returns true if the authenticated user has at least ONE of the scopes (or permissions) in needed (logical OR). Like hasScope, it checks both the scopes and permissions arrays, and reads auth via getAuth, so it throws on a request with no verified auth. Unlike hasScope, this takes an array only.

import { hasAnyScope } from "mcp-use/server";

Parameters

Context
required
Hono context, typically the tool’s requestContext parameter.

string[]
required
Array of scopes/permissions; the user needs at least one of them.

Returns

boolean

Signature

function hasAnyScope(context: Context, needed: string[]): boolean

requireScope

Builds a Hono middleware that enforces every scope (or permission) in needed, returning 403 when the check fails.

import { requireScope } from "mcp-use/server";

Builds a Hono middleware that enforces that the user has every scope (or permission) in needed before the route runs. If the check fails it short-circuits with HTTP 403 and does not call next. If it passes it calls next. A single string is treated as a one element list; an array requires ALL entries (logical AND), matching hasScope. The 403 JSON body is { error: "insufficient_scope", required, granted_scopes, granted_permissions, message }, where granted_scopes and granted_permissions come from the current AuthInfo. For per-tool checks, prefer calling hasScope inside the tool callback instead of this route middleware.

import { requireScope } from "mcp-use/server";

Parameters

string | string[]
required
A single scope/permission, or an array of scopes/permissions that must ALL be present.

Returns

(c: Context, next: Next) => Promise<Response | void>
A Hono middleware function. Returns a 403 JSON response when the scope check fails, otherwise resolves after calling next.

Signature

function requireScope(needed: string | string[]): (c: Context, next: Next) => Promise<Response | void>

requireAnyScope

Builds a Hono middleware that enforces at least ONE of the scopes (or permissions) in needed (logical OR), returning 403 when the check fails.

import { requireAnyScope } from "mcp-use/server";

Builds a Hono middleware that enforces that the user has at least ONE of the scopes (or permissions) in needed (logical OR) before the route runs. If the check fails it short-circuits with HTTP 403; otherwise it calls next. Takes an array only. The 403 JSON body is { error: "insufficient_scope", required_any, granted_scopes, granted_permissions, message }. For per-tool checks, prefer calling hasAnyScope inside the tool callback instead.

import { requireAnyScope } from "mcp-use/server";

Parameters

string[]
required
Array of scopes/permissions; the user needs at least one of them.

Returns

(c: Context, next: Next) => Promise<Response | void>
A Hono middleware function. Returns a 403 JSON response when the scope check fails, otherwise resolves after calling next.

Signature

function requireAnyScope(needed: string[]): (c: Context, next: Next) => Promise<Response | void>

jwksVerifier

Builds a VerifyToken function that validates JWTs against a remote JWKS using jose.

import { jwksVerifier } from "mcp-use/server";

Builds a VerifyToken function that validates JWTs against a remote JWKS (JSON Web Key Set) using jose. The returned function performs signature verification, issuer checking, and, if an audience is configured, audience checking. Pass the result as the verifyToken field of oauthProxy(...) for standard JWT/JWKS providers such as Auth0, Okta, or Google. createRemoteJWKSet is created eagerly but does not fetch keys until the first verify call, so constructing the verifier is cheap. The factory throws if jwksUrl is missing ("jwksVerifier: jwksUrl is required") or if issuer is missing ("jwksVerifier: issuer is required"). At verify time, a token that is not a signed JWT (it lacks exactly three dot-separated segments, as with the opaque tokens some providers issue when no valid audience is requested) is rejected early with a descriptive error pointing at the audience configuration. Any other verification failure is wrapped and rethrown as JWKS verification failed: <error>.

import { jwksVerifier } from "mcp-use/server";

Parameters

JwksVerifierConfig
required
JWKS endpoint, expected issuer, and optional audience. See JwksVerifierConfig.

Returns

VerifyToken
An async function that verifies a bearer token and resolves to its decoded payload, or throws if the token is invalid.

Signature

function jwksVerifier(config: JwksVerifierConfig): VerifyToken

Types

AuthInfo

The authentication information the bearer middleware attaches to each verified request.

import type { AuthInfo } from "mcp-use/server";

The authentication information the bearer middleware attaches to each verified request. getAuth returns this shape, and it is also exposed directly as ctx.auth inside tool callbacks. user is the extracted UserInfo. payload is the raw verified token payload. scopes is parsed from the token’s space-delimited scope claim (empty array when absent). permissions comes from the token’s permissions claim (Auth0 style; empty array when absent).

import type { AuthInfo } from "mcp-use/server";

Properties

UserInfo
required
The authenticated user, extracted from the token payload.

Record<string, unknown>
required
The raw verified JWT payload.

string
required
The bearer access token from the Authorization header.

string[]
required
OAuth scopes parsed from the scope claim. Empty array if the claim is absent.

string[]
required
Permissions from the permissions claim (Auth0 style). Empty array if the claim is absent.

Definition

interface AuthInfo {
  user: UserInfo
  payload: Record<string, unknown>
  accessToken: string
  scopes: string[]
  permissions: string[]
}

UserInfo

User information extracted from a verified OAuth token.

import type { UserInfo } from "mcp-use/server";

User information extracted from a verified OAuth token. userId is the only required field (mapped from the sub claim by the default extractor); all other fields are optional and depend on the provider and on the token’s claims. The interface has an index signature, so additional custom claims are allowed and preserved (for example WorkOS surfaces organization_id this way).

import type { UserInfo } from "mcp-use/server";

Properties

string
required
Stable user identifier, typically the sub claim.

string
User email, if present in the token.

string
Display name, if present.

string
Username, if present.

string
Nickname, if present.

string
Avatar/picture URL, if present.

string[]
Roles, if present.

string[]
Permissions, if present.

unknown
Index signature for any additional custom claims.

Definition

interface UserInfo {
  userId: string
  email?: string
  name?: string
  username?: string
  nickname?: string
  picture?: string
  roles?: string[]
  permissions?: string[]
  [key: string]: unknown
}

VerifyToken

A token verification function that resolves to the decoded payload, or throws if the token is invalid.

import type { VerifyToken } from "mcp-use/server";

A token verification function: it takes a bearer token string and resolves to an object containing the decoded payload, or throws if the token is invalid. This is the type returned by jwksVerifier and accepted by oauthProxy as its verifyToken field. Provide a custom implementation for non-JWT providers (for example, GitHub opaque tokens validated by an API call).

import type { VerifyToken } from "mcp-use/server";

Definition

type VerifyToken = (token: string) => Promise<{ payload: Record<string, unknown> }>

JwksVerifierConfig

Configuration for the built-in JWKS verifier created by jwksVerifier.

import type { JwksVerifierConfig } from "mcp-use/server";

Configuration for the built-in JWKS verifier created by jwksVerifier. jwksUrl and issuer are required (the factory throws if either is missing); audience is optional and, when set, rejects tokens without a matching aud claim.

import type { JwksVerifierConfig } from "mcp-use/server";

Properties

string
required
JWKS endpoint URL (the provider’s public key set), for example https://your-domain.okta.com/oauth2/default/v1/keys.

string
required
Expected iss claim. Tokens whose issuer does not match are rejected.

string
Expected aud claim. When set, tokens without a matching audience are rejected.

Definition

interface JwksVerifierConfig {
  jwksUrl: string
  issuer: string
  audience?: string
}

OAuthProvider

The contract every OAuth provider implements: token verification, user info extraction, and OAuth metadata getters.

import type { OAuthProvider } from "mcp-use/server";

The contract every OAuth provider implements: token verification, user info extraction, and OAuth metadata getters. The provider factory functions (such as oauthAuth0Provider and oauthWorkOSProvider) return values of this type, and you pass one as the oauth option of MCPServer. getUserInfoEndpoint and getAudience are optional. OAuthProxy extends this interface with proxy-specific fields for providers without Dynamic Client Registration.

import type { OAuthProvider } from "mcp-use/server";

Methods

(token: string) => Promise<{ payload: Record<string, unknown> }>
required
Verify and decode a token. Throws if the token is invalid.

(payload: Record<string, unknown>) => UserInfo | Promise<UserInfo>
required
Extract user information from a verified token payload.

() => string
required
Return the OAuth issuer URL.

() => string
required
Return the authorization endpoint URL.

() => string
required
Return the token endpoint URL.

() => string[]
required
Return the supported OAuth scopes.

() => string[]
required
Return the supported grant types.

() => string | undefined
Optional. Return the user info endpoint URL, or undefined if not configured.

() => string | undefined
Optional. Return the audience for JWT verification, or undefined if not configured.

Definition

interface OAuthProvider {
  verifyToken(token: string): Promise<{ payload: Record<string, unknown> }>
  getUserInfo(payload: Record<string, unknown>): UserInfo | Promise<UserInfo>
  getIssuer(): string
  getAuthEndpoint(): string
  getTokenEndpoint(): string
  getScopesSupported(): string[]
  getGrantTypesSupported(): string[]
  getUserInfoEndpoint?(): string | undefined
  getAudience?(): string | undefined
}

Usage

Configure a provider on the server, then read the authenticated user inside a tool via ctx.auth (an AuthInfo). This example uses the Auth0 provider, configured entirely from MCP_USE_OAUTH_* environment variables.

import { MCPServer, oauthAuth0Provider, object } from "mcp-use/server";

const server = new MCPServer({
  name: "auth0-oauth-example",
  version: "1.0.0",
  description: "MCP server with Auth0 OAuth authentication",
  // Zero-config: OAuth is configured via MCP_USE_OAUTH_* environment variables
  oauth: oauthAuth0Provider(),
});

server.tool(
  {
    name: "get-user-info",
    description: "Get information about the authenticated user",
  },
  async (_args, ctx) =>
    object({
      userId: ctx.auth.user.userId,
      email: ctx.auth.user.email,
      name: ctx.auth.user.name,
      nickname: ctx.auth.user.nickname,
      picture: ctx.auth.user.picture,
      permissions: ctx.auth.permissions,
      scopes: ctx.auth.scopes,
    })
);

server.listen().then(() => {
  console.log("Auth0 OAuth MCP Server Running");
});

To gate a tool by scope, call hasScope (or hasAnyScope) inside the callback and return your own error result when the check fails. To gate a custom route, mount requireScope (or requireAnyScope) as middleware.

Overview

Server

React

Client

Agent

Authentication helpers

Functions

getAuth

hasScope

hasAnyScope

requireScope

requireAnyScope

jwksVerifier

Types

AuthInfo

UserInfo

VerifyToken

JwksVerifierConfig

OAuthProvider

Usage

​Functions

​getAuth

​hasScope

​hasAnyScope

​requireScope

​requireAnyScope

​jwksVerifier

​Types

​AuthInfo

​UserInfo

​VerifyToken

​JwksVerifierConfig

​OAuthProvider

​Usage

Functions

getAuth

hasScope

hasAnyScope

requireScope

requireAnyScope

jwksVerifier

Types

AuthInfo

UserInfo

VerifyToken

JwksVerifierConfig

OAuthProvider

Usage