> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-use.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth providers

> OAuth provider factories and proxy helpers for MCP servers API Documentation

**Source Code**

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](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/server/oauth/index.ts)](https://github.com/mcp-use/mcp-use/blob/main/libraries/typescript/packages/mcp-use/src/server/oauth/index.ts)

These factory functions build the `oauth` value you pass to [`new MCPServer({ ... })`](https://docs.mcp-use.com/v1/typescript/api-reference/server/mcp-server). Each one returns an `OAuthProvider` (or `OAuthProxy`) that the server uses to verify bearer tokens, proxy `.well-known` metadata discovery, and extract user info onto `ctx.auth`.

There are two integration modes:

* **DCR-direct providers** (`oauthAuth0Provider`, `oauthBetterAuthProvider`, `oauthClerkProvider`, `oauthKeycloakProvider`, `oauthSupabaseProvider`, `oauthWorkOSProvider`, `oauthCustomProvider`). The MCP server proxies metadata discovery to the upstream authorization server and verifies tokens. Clients communicate directly with the upstream for authorize, token, and register.
* **Proxy mode** (`oauthProxy`) for providers without Dynamic Client Registration support (Google, GitHub, Okta, Microsoft Entra ID, and enterprise IdPs). The server mediates the flow: it exposes a `/register` endpoint returning the configured `clientId`, injects `clientId`/`clientSecret` at token exchange, and passes upstream tokens through without minting its own.

All factories import from `mcp-use/server`.

```ts wrap theme={null}
import { oauthAuth0Provider, oauthProxy, jwksVerifier } from "mcp-use/server";
```

## Functions

### oauthAuth0Provider

Create an Auth0 OAuth provider for an MCP server.

```ts theme={null}
import { oauthAuth0Provider } from "mcp-use/server";
```

Builds an `OAuthProvider` backed by Auth0. Supports zero-config setup: when `config` is omitted, `domain` falls back to `MCP_USE_OAUTH_AUTH0_DOMAIN` and `audience` falls back to `MCP_USE_OAUTH_AUTH0_AUDIENCE`. Throws `Error` if `domain` is missing (`"Auth0 domain is required."`) and throws `Error` if `audience` is missing (`"Auth0 audience is required."`). The `config` argument is `Partial<Auth0ProviderConfig>` and defaults to an empty object.

**Parameters**

> **config** `Partial\<Auth0ProviderConfig\>` (default: \{})
>
> &#x20;
>
> Optional Auth0 configuration. Values passed here override the corresponding
> environment variables.&#x20;

**Returns**

> **returns** `OAuthProvider`

**Signature**

```ts wrap theme={null}
function oauthAuth0Provider(
  config?: Partial<Auth0ProviderConfig>,
): OAuthProvider;
```

**Example**

```ts wrap theme={null}
import { MCPServer, oauthAuth0Provider, error, object } from "mcp-use/server";

// Zero-config: reads MCP_USE_OAUTH_AUTH0_DOMAIN and MCP_USE_OAUTH_AUTH0_AUDIENCE
const server = new MCPServer({
  name: "auth0-oauth-example",
  version: "1.0.0",
  description: "MCP server with Auth0 OAuth authentication",
  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,
      permissions: ctx.auth.permissions,
      scopes: ctx.auth.scopes,
    }),
);

server.listen();
```

### oauthBetterAuthProvider

Create a Better Auth OAuth provider for an MCP server.

```ts theme={null}
import { oauthBetterAuthProvider } from "mcp-use/oauth/better-auth";
```

Builds an `OAuthProvider` backed by Better Auth's OAuth Provider plugin. The MCP server advertises Better Auth's `/oauth2/authorize`, `/oauth2/token`, and `/oauth2/register` endpoints and verifies access-token JWTs against `/jwks`. Your application creates and mounts Better Auth separately.

**Parameters**

> **options** `BetterAuthOAuthProviderOptions`
>
> &#x20;
>
> Better Auth issuer URL and optional MCP resource metadata.&#x20;

**Returns**

> **returns** `OAuthProvider\<BetterAuthOAuthUser\>`

**Signature**

```ts wrap theme={null}
function oauthBetterAuthProvider(
  options: BetterAuthOAuthProviderOptions,
): OAuthProvider<BetterAuthOAuthUser>;
```

**Example**

```ts wrap theme={null}
import { MCPServer } from "mcp-use";
import { oauthBetterAuthProvider } from "mcp-use/oauth/better-auth";

const server = new MCPServer({
  name: "better-auth-oauth-example",
  version: "1.0.0",
  description: "MCP server with Better Auth OAuth authentication",
  oauth: oauthBetterAuthProvider({
    authURL: "http://localhost:61843/api/auth",
    resource: "http://localhost:43127/mcp",
  }),
});
```

### oauthClerkProvider

Create a Clerk OAuth provider for an MCP server.

```ts theme={null}
import { oauthClerkProvider } from "mcp-use/server";
```

Builds an `OAuthProvider` backed by Clerk. Uses Dynamic Client Registration: clients register themselves with Clerk (enable DCR in the Clerk Dashboard under Configure, OAuth Applications, Dynamic Client Registration), and the MCP server only verifies Clerk-issued tokens. `frontendApiUrl` falls back to `MCP_USE_OAUTH_CLERK_FRONTEND_API_URL`. Throws `Error` if `frontendApiUrl` is missing (`"Clerk frontendApiUrl is required."`). The `config` argument is `Partial<ClerkProviderConfig>` and defaults to an empty object.

**Parameters**

> **config** `Partial\<ClerkProviderConfig\>` (default: \{})
>
> &#x20;
>
> Optional Clerk configuration. Values passed here override the corresponding
> environment variables.&#x20;

**Returns**

> **returns** `OAuthProvider`

**Signature**

```ts wrap theme={null}
function oauthClerkProvider(
  config?: Partial<ClerkProviderConfig>,
): OAuthProvider;
```

**Example**

```ts wrap theme={null}
import { MCPServer, oauthClerkProvider, object } from "mcp-use/server";

// Zero-config: reads MCP_USE_OAUTH_CLERK_FRONTEND_API_URL
const server = new MCPServer({
  name: "clerk-oauth-example",
  version: "1.0.0",
  description: "MCP server with Clerk OAuth authentication",
  oauth: oauthClerkProvider(),
});

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,
    }),
);

server.listen();
```

### oauthKeycloakProvider

Create a Keycloak OAuth provider for an MCP server.

```ts theme={null}
import { oauthKeycloakProvider } from "mcp-use/server";
```

Builds an `OAuthProvider` backed by Keycloak using its native Dynamic Client Registration (RFC 7591). `serverUrl` falls back to `MCP_USE_OAUTH_KEYCLOAK_SERVER_URL`, `realm` falls back to `MCP_USE_OAUTH_KEYCLOAK_REALM`, and `audience` falls back to `MCP_USE_OAUTH_KEYCLOAK_AUDIENCE`. Throws `Error` if `serverUrl` is missing (`"Keycloak serverUrl is required."`) and throws `Error` if `realm` is missing (`"Keycloak realm is required."`). The `config` argument is `Partial<KeycloakProviderConfig>` and defaults to an empty object.

**Parameters**

> **config** `Partial\<KeycloakProviderConfig\>` (default: \{})
>
> &#x20;
>
> Optional Keycloak configuration. Values passed here override the
> corresponding environment variables.&#x20;

**Returns**

> **returns** `OAuthProvider`

**Signature**

```ts wrap theme={null}
function oauthKeycloakProvider(
  config?: Partial<KeycloakProviderConfig>,
): OAuthProvider;
```

**Example**

```ts wrap theme={null}
import { MCPServer, oauthKeycloakProvider, object } from "mcp-use/server";

const server = new MCPServer({
  name: "keycloak-oauth-example",
  version: "1.0.0",
  description: "MCP server with Keycloak OAuth authentication (DCR)",
  oauth: oauthKeycloakProvider({
    serverUrl: "http://localhost:8080",
    realm: "demo",
  }),
});

server.tool(
  {
    name: "get-user-info",
    description:
      "Return identity info extracted from the Keycloak access token",
  },
  async (_args, ctx) =>
    object({
      userId: ctx.auth.user.userId,
      username: ctx.auth.user.username,
      email: ctx.auth.user.email,
      roles: ctx.auth.user.roles,
    }),
);
```

### oauthSupabaseProvider

Create a Supabase OAuth provider for an MCP server.

```ts theme={null}
import { oauthSupabaseProvider } from "mcp-use/server";
```

Builds an `OAuthProvider` backed by Supabase's OAuth 2.1 server. Supports zero-config setup: `projectId` falls back to `MCP_USE_OAUTH_SUPABASE_PROJECT_ID`, `supabaseUrl` falls back to `MCP_USE_OAUTH_SUPABASE_URL`, and `jwtSecret` falls back to `MCP_USE_OAUTH_SUPABASE_JWT_SECRET`. The hosted URL is derived as `https://${projectId}.supabase.co` unless `supabaseUrl` is set (use `supabaseUrl` for local or self-hosted instances, e.g. `http://localhost:54321`). Throws `Error` if neither `projectId` nor `supabaseUrl` is resolved (`"Supabase projectId or supabaseUrl is required."`). The `config` argument is `Partial<SupabaseProviderConfig>` and defaults to an empty object.

**Parameters**

> **config** `Partial\<SupabaseProviderConfig\>` (default: \{})
>
> &#x20;
>
> Optional Supabase configuration. Values passed here override the
> corresponding environment variables.&#x20;

**Returns**

> **returns** `OAuthProvider`

**Signature**

```ts wrap theme={null}
function oauthSupabaseProvider(
  config?: Partial<SupabaseProviderConfig>,
): OAuthProvider;
```

**Example**

```ts wrap theme={null}
import { MCPServer, oauthSupabaseProvider } from "mcp-use/server";

// Zero-config: reads MCP_USE_OAUTH_SUPABASE_PROJECT_ID
const server = new MCPServer({
  name: "supabase-oauth-example",
  version: "1.0.0",
  description: "MCP server with Supabase OAuth authentication",
  oauth: oauthSupabaseProvider(),
});
```

### oauthWorkOSProvider

Create a WorkOS AuthKit OAuth provider for an MCP server.

```ts theme={null}
import { oauthWorkOSProvider } from "mcp-use/server";
```

Builds an `OAuthProvider` backed by WorkOS AuthKit using Dynamic Client Registration. Clients register themselves with WorkOS (enable DCR in the WorkOS Dashboard under Connect, Configuration), and the MCP server only verifies WorkOS-issued tokens. `subdomain` falls back to `MCP_USE_OAUTH_WORKOS_SUBDOMAIN`. Throws `Error` if `subdomain` is missing (`"WorkOS subdomain is required."`). The `config` argument is `Partial<WorkOSProviderConfig>` and defaults to an empty object.

**Parameters**

> **config** `Partial\<WorkOSProviderConfig\>` (default: \{})
>
> &#x20;
>
> Optional WorkOS configuration. Values passed here override the corresponding
> environment variables.&#x20;

**Returns**

> **returns** `OAuthProvider`

**Signature**

```ts wrap theme={null}
function oauthWorkOSProvider(
  config?: Partial<WorkOSProviderConfig>,
): OAuthProvider;
```

**Example**

```ts wrap theme={null}
import { MCPServer, oauthWorkOSProvider } from "mcp-use/server";

// Zero-config: reads MCP_USE_OAUTH_WORKOS_SUBDOMAIN
const server = new MCPServer({
  name: "workos-oauth-example",
  version: "1.0.0",
  description: "MCP server with WorkOS AuthKit OAuth authentication",
  oauth: oauthWorkOSProvider(),
});
```

### oauthCustomProvider

Create an OAuth provider for any standards-compliant authorization server.

```ts theme={null}
import { oauthCustomProvider } from "mcp-use/server";
```

Builds an `OAuthProvider` from explicit endpoint URLs and a custom `verifyToken` function. Unlike the other factories, `config` is required (there are no environment-variable fallbacks). Use this for any OAuth provider that exposes standard `.well-known` discovery and an authorization plus token endpoint, where you supply your own token verification logic.

**Parameters**

> **config** `CustomProviderConfig` *required*
>
> &#x20;
>
> Custom provider configuration with explicit endpoints and a `verifyToken`
> function.&#x20;

**Returns**

> **returns** `OAuthProvider`

**Signature**

```ts wrap theme={null}
function oauthCustomProvider(config: CustomProviderConfig): OAuthProvider;
```

**Example**

```ts wrap theme={null}
import { MCPServer, oauthCustomProvider } from "mcp-use/server";

const server = new MCPServer({
  name: "my-server",
  version: "1.0.0",
  oauth: oauthCustomProvider({
    issuer: "https://oauth.example.com",
    jwksUrl: "https://oauth.example.com/.well-known/jwks.json",
    authEndpoint: "https://oauth.example.com/authorize",
    tokenEndpoint: "https://oauth.example.com/token",
    verifyToken: async (token) => {
      // Custom verification logic; return { payload }
      return { payload: {} };
    },
  }),
});
```

### oauthProxy

Create an OAuth proxy for providers without Dynamic Client Registration.

```ts theme={null}
import { oauthProxy, jwksVerifier } from "mcp-use/server";
```

Builds an `OAuthProxy` for providers that lack DCR support (Google OAuth, GitHub OAuth, Okta, Microsoft Entra ID, and enterprise IdPs). The proxy exposes a `/register` endpoint that returns the configured `clientId`, injects `clientId`/`clientSecret` at token exchange, verifies tokens via the supplied `verifyToken` function, and passes upstream tokens through without minting its own. `scopes` defaults to `["openid", "email", "profile"]` and `grantTypes` defaults to `["authorization_code", "refresh_token"]`. When `getUserInfo` is omitted, a default extractor reads the standard OIDC claims (`sub`, `email`, `name`, `picture`) and splits the `scope` claim into `scopes`.

Throws `Error` if any of `authEndpoint`, `tokenEndpoint`, `issuer`, `clientId`, or `verifyToken` is missing. The verifyToken error message points you to `jwksVerifier()` for JWT/JWKS providers.

Pair `oauthProxy` with `jwksVerifier()` (exported from `mcp-use/server`) to verify JWTs against a remote JWKS. `jwksVerifier` enforces the `iss` claim, optionally enforces `aud`, and throws early with a helpful message if the token is not a three-segment signed JWT (for example, when an authorize request omitted a valid `audience` and the provider issued an opaque token).

**Parameters**

> **config** `OAuthProxyConfig` *required*
>
> &#x20;
>
> OAuth proxy configuration including upstream endpoints, client credentials,
> and a `verifyToken` function.&#x20;

**Returns**

> **returns** `OAuthProxy`

**Signature**

```ts wrap theme={null}
function oauthProxy(config: OAuthProxyConfig): OAuthProxy;
```

**Example**

```ts wrap theme={null}
import {
  MCPServer,
  oauthProxy,
  jwksVerifier,
  object,
  error,
} from "mcp-use/server";

const issuer = process.env.OKTA_ISSUER!;
const clientId = process.env.OKTA_CLIENT_ID!;
const clientSecret = process.env.OKTA_CLIENT_SECRET;

const server = new MCPServer({
  name: "okta-proxy-example",
  version: "1.0.0",
  description: "MCP server with Okta OAuth proxy authentication",
  oauth: oauthProxy({
    authEndpoint: `${issuer}/v1/authorize`,
    tokenEndpoint: `${issuer}/v1/token`,
    issuer,
    clientId,
    clientSecret,
    scopes: ["openid", "email", "profile"],
    verifyToken: jwksVerifier({
      jwksUrl: `${issuer}/v1/keys`,
      issuer,
      audience: clientId,
    }),
  }),
});

server.listen();
```

### mountOAuthProxy

Mount CORS-free OAuth proxy routes on a Hono app.

```ts theme={null}
import { mountOAuthProxy } from "mcp-use/server";
```

Mounts a server-side OAuth BFF for browser MCP clients. This is distinct from `oauthProxy`, which configures the MCP server's own authentication.

Both routes require a logical `serverUrl`. `GET <basePath>/metadata?serverUrl=...&url=...` accepts only protected-resource metadata derived from that MCP URL and authorization-server metadata advertised by the protected resource. `POST <basePath>/proxy` accepts `{ serverUrl, url, method: "POST", headers, body }` only after discovery has bound `url` to the advertised registration, token, revocation, or introspection endpoint. Authorization navigation is never proxied.

Targets must use HTTPS. Loopback HTTP(S) is available only with the explicit local-development option. Private and non-routable addresses, redirects, unsafe headers, oversized bodies, and cross-origin callers not listed in `allowedOrigins` are rejected. Same-origin calls are always accepted. Metadata is returned unchanged; the BFF does not rewrite `resource` or add private fields.

**Parameters**

> **app** `Hono` *required*
>
> &#x20;
>
> The Hono application instance to register routes on.&#x20;
>
> **options** `OAuthProxyOptions` (default: \{})
>
> &#x20;
>
> Configuration options for the proxy routes.&#x20;

**Returns**

> **returns** `void`

**Signature**

```ts wrap theme={null}
function mountOAuthProxy(app: Hono, options?: OAuthProxyOptions): void;
```

**Example**

```ts wrap theme={null}
import { Hono } from "hono";
import { mountOAuthProxy } from "mcp-use/server";

const app = new Hono();

// Same-origin, HTTPS-only usage at the default /oauth base path
mountOAuthProxy(app);

// Explicit local development policy
mountOAuthProxy(app, {
  basePath: "/inspector/api/oauth",
  allowedOrigins: ["http://localhost:3000"],
  allowLoopback: true,
});
```

## Types

### Auth0ProviderConfig

Configuration for `oauthAuth0Provider`.

```ts theme={null}
import type { Auth0ProviderConfig } from "mcp-use/server";
```

Configuration for the Auth0 provider. `oauthAuth0Provider` accepts `Partial<Auth0ProviderConfig>` and fills any missing `domain`/`audience` from environment variables.

**Properties**

> **domain** `string` *required*
>
> &#x20;
>
> Auth0 tenant domain, e.g. `my-tenant.auth0.com`.&#x20;
>
> **audience** `string` *required*
>
> &#x20;
>
> API identifier used as the JWT `aud` claim.&#x20;
>
> **verifyJwt** `boolean`
>
> &#x20;
>
> Whether to verify the JWT signature.&#x20;
>
> **scopesSupported** `string[]`
>
> &#x20;
>
> Scopes advertised in metadata.&#x20;

**Signature**

```ts wrap theme={null}
interface Auth0ProviderConfig {
  domain: string;
  audience: string;
  verifyJwt?: boolean;
  scopesSupported?: string[];
}
```

### BetterAuthOAuthProviderOptions

Configuration for `oauthBetterAuthProvider`.

```ts theme={null}
import type { BetterAuthOAuthProviderOptions } from "mcp-use/oauth/better-auth";
```

Configuration for the Better Auth provider. It includes the shared OAuth resource options (`resource`, `requiredScopes`, `scopesSupported`, `resourceName`, and `serviceDocumentationUrl`).

**Properties**

> **authURL** `string` *required*
>
> &#x20;
>
> Base URL of the Better Auth OAuth server, e.g.
> `http://localhost:61843/api/auth`. This may be a different origin from the
> MCP resource server.&#x20;
>
> **scopesSupported** `string[]`
>
> &#x20;
>
> Scopes advertised in metadata.&#x20;
>
> **Signature**

```ts wrap theme={null}
interface BetterAuthOAuthProviderOptions extends OAuthResourceOptions {
  authURL: URL | string;
}
```

### ClerkProviderConfig

Configuration for `oauthClerkProvider`.

```ts theme={null}
import type { ClerkProviderConfig } from "mcp-use/server";
```

Configuration for the Clerk provider. `frontendApiUrl` falls back to `MCP_USE_OAUTH_CLERK_FRONTEND_API_URL`.

**Properties**

> **frontendApiUrl** `string` *required*
>
> &#x20;
>
> Clerk Frontend API URL, e.g. `https://verb-noun-42.clerk.accounts.dev` or
> `https://clerk.yourdomain.com`.&#x20;
>
> **audience** `string`
>
> &#x20;
>
> Optional audience for JWT verification.&#x20;
>
> **verifyJwt** `boolean`
>
> &#x20;
>
> Whether to verify the JWT signature.&#x20;
>
> **scopesSupported** `string[]`
>
> &#x20;
>
> Scopes advertised in metadata.&#x20;

**Signature**

```ts wrap theme={null}
interface ClerkProviderConfig {
  frontendApiUrl: string;
  audience?: string;
  verifyJwt?: boolean;
  scopesSupported?: string[];
}
```

### KeycloakProviderConfig

Configuration for `oauthKeycloakProvider`.

```ts theme={null}
import type { KeycloakProviderConfig } from "mcp-use/server";
```

Configuration for the Keycloak provider. `serverUrl` falls back to `MCP_USE_OAUTH_KEYCLOAK_SERVER_URL`, `realm` to `MCP_USE_OAUTH_KEYCLOAK_REALM`, and `audience` to `MCP_USE_OAUTH_KEYCLOAK_AUDIENCE`.

**Properties**

> **serverUrl** `string` *required*
>
> &#x20;
>
> Keycloak base URL, e.g. `https://keycloak.example.com`.&#x20;
>
> **realm** `string` *required*
>
> &#x20;
>
> Keycloak realm name.&#x20;
>
> **audience** `string`
>
> &#x20;
>
> MCP server URL used to validate the JWT `aud` claim (set via a Keycloak
> audience mapper on client scopes).&#x20;
>
> **verifyJwt** `boolean`
>
> &#x20;
>
> Whether to verify the JWT signature.&#x20;
>
> **scopesSupported** `string[]`
>
> &#x20;
>
> Scopes advertised in metadata.&#x20;

**Signature**

```ts wrap theme={null}
interface KeycloakProviderConfig {
  serverUrl: string;
  realm: string;
  audience?: string;
  verifyJwt?: boolean;
  scopesSupported?: string[];
}
```

### SupabaseProviderConfig

Configuration for `oauthSupabaseProvider`.

```ts theme={null}
import type { SupabaseProviderConfig } from "mcp-use/server";
```

Configuration for the Supabase provider. Either `projectId` or `supabaseUrl` must resolve (from config or environment). `projectId` derives the hosted URL `https://${projectId}.supabase.co`; `supabaseUrl` overrides it for self-hosted or local instances.

**Properties**

> **projectId** `string`
>
> &#x20;
>
> Supabase project ID used to derive the hosted URL.&#x20;
>
> **supabaseUrl** `string`
>
> &#x20;
>
> Explicit Supabase base URL. Overrides the projectId-derived URL, e.g.
> `http://localhost:54321`.&#x20;
>
> **jwtSecret** `string`
>
> &#x20;
>
> Optional JWT secret for legacy HS256 token verification.&#x20;
>
> **verifyJwt** `boolean`
>
> &#x20;
>
> Whether to verify the JWT signature.&#x20;
>
> **scopesSupported** `string[]`
>
> &#x20;
>
> Scopes advertised in metadata.&#x20;

**Signature**

```ts wrap theme={null}
interface SupabaseProviderConfig {
  projectId?: string;
  supabaseUrl?: string;
  jwtSecret?: string;
  verifyJwt?: boolean;
  scopesSupported?: string[];
}
```

### WorkOSProviderConfig

Configuration for `oauthWorkOSProvider`.

```ts theme={null}
import type { WorkOSProviderConfig } from "mcp-use/server";
```

Configuration for the WorkOS provider. `subdomain` falls back to `MCP_USE_OAUTH_WORKOS_SUBDOMAIN`.

**Properties**

> **subdomain** `string` *required*
>
> &#x20;
>
> WorkOS AuthKit subdomain, e.g. `my-company.authkit.app`.&#x20;
>
> **verifyJwt** `boolean`
>
> &#x20;
>
> Whether to verify the JWT signature.&#x20;
>
> **scopesSupported** `string[]`
>
> &#x20;
>
> Scopes advertised in metadata.&#x20;

**Signature**

```ts wrap theme={null}
interface WorkOSProviderConfig {
  subdomain: string;
  verifyJwt?: boolean;
  scopesSupported?: string[];
}
```

### CustomProviderConfig

Configuration for `oauthCustomProvider`.

```ts theme={null}
import type { CustomProviderConfig } from "mcp-use/server";
```

Configuration for an arbitrary OAuth provider. `issuer`, `authEndpoint`, `tokenEndpoint`, and `verifyToken` are required; the rest are optional. `verifyToken` resolves to an object containing a `payload` (see the signature fence for the exact type, which contains a curly brace). The optional `getUserInfo` callback maps a payload to a `UserInfo`.

**Properties**

> **issuer** `string` *required*
>
> &#x20;
>
> OAuth issuer URL.&#x20;
>
> **authEndpoint** `string` *required*
>
> &#x20;
>
> Authorization endpoint URL.&#x20;
>
> **tokenEndpoint** `string` *required*
>
> &#x20;
>
> Token endpoint URL.&#x20;
>
> **verifyToken** `(token) =\> Promise\<any\>` *required*
>
> &#x20;
>
> Function that verifies a bearer token and resolves to its decoded
> payload.&#x20;
>
> **jwksUrl** `string`
>
> &#x20;
>
> JWKS endpoint URL for signature verification.&#x20;
>
> **userInfoEndpoint** `string`
>
> &#x20;
>
> User info endpoint URL.&#x20;
>
> **scopesSupported** `string[]`
>
> &#x20;
>
> Scopes advertised in metadata.&#x20;
>
> **audience** `string`
>
> &#x20;
>
> Audience for JWT verification.&#x20;
>
> **grantTypesSupported** `string[]`
>
> &#x20;
>
> Grant types advertised in metadata.&#x20;
>
> **getUserInfo** `(payload) =\> UserInfo`
>
> &#x20;
>
> Optional callback mapping a verified payload to user info.&#x20;

**Signature**

```ts wrap theme={null}
interface CustomProviderConfig {
  issuer: string;
  authEndpoint: string;
  tokenEndpoint: string;
  verifyToken: (token: string) => Promise<any>;
  jwksUrl?: string;
  userInfoEndpoint?: string;
  scopesSupported?: string[];
  audience?: string;
  grantTypesSupported?: string[];
  getUserInfo?: (payload: any) => UserInfo;
}
```

### OAuthProxy

The proxy-mode provider returned by `oauthProxy`.

```ts theme={null}
import type { OAuthProxy } from "mcp-use/server";
```

Extends `OAuthProvider` with proxy-specific fields for providers without DCR support. Implements the full provider interface (the getter methods plus `verifyToken`/`getUserInfo`) and adds a `type` discriminator, pre-registered client credentials, and optional extra authorize params. The proxy exposes a `/register` endpoint returning the configured `clientId`, injects `clientId`/`clientSecret` at token exchange, and passes upstream JWTs through without minting tokens.

**Properties**

> **type** `"proxy"` *required*
>
> &#x20;
>
> Discriminator used to detect proxy providers in the provider union.&#x20;
>
> **clientId** `string` *required*
>
> &#x20;
>
> Pre-registered OAuth client ID.&#x20;
>
> **clientSecret** `string`
>
> &#x20;
>
> Pre-registered OAuth client secret (optional for public clients).&#x20;
>
> **extraAuthorizeParams** `Record\<string, string\>`
>
> &#x20;
>
> Extra parameters appended to authorize requests.&#x20;

**Signature**

```ts wrap theme={null}
interface OAuthProxy extends OAuthProvider {
  type: "proxy";
  clientId: string;
  clientSecret?: string;
  extraAuthorizeParams?: Record<string, string>;
}
```

### OAuthProxyConfig

Configuration for `oauthProxy`.

```ts theme={null}
import type { OAuthProxyConfig } from "mcp-use/server";
```

Configuration for creating an OAuth proxy. `authEndpoint`, `tokenEndpoint`, `issuer`, `clientId`, and `verifyToken` are required. `scopes` defaults to `["openid", "email", "profile"]` and `grantTypes` defaults to `["authorization_code", "refresh_token"]` inside `oauthProxy`. The `verifyToken` field is a `VerifyToken` function that resolves to an object with a `payload` (see the signature fence for the exact type, which contains a curly brace). When `getUserInfo` is omitted, standard OIDC claims are extracted.

**Properties**

> **authEndpoint** `string` *required*
>
> &#x20;
>
> Upstream authorization endpoint URL, e.g.
> `https://accounts.google.com/o/oauth2/v2/auth`.&#x20;

**tokenEndpoint** `string` *required*

Upstream token endpoint URL, e.g. `https://oauth2.googleapis.com/token`.

**issuer** `string` *required*

Token issuer, used in metadata and (when paired with `jwksVerifier`) enforced as the `iss` claim.

**verifyToken** `VerifyToken` *required*

Token verification function. Use `jwksVerifier()` for JWT+JWKS providers, or write your own for opaque tokens.

**clientId** `string` *required*

Pre-registered OAuth client ID.

**clientSecret** `string`

Pre-registered OAuth client secret (optional for public clients).

**scopes** `string[]` (default: \["openid", "email", "profile"])

OAuth scopes to request.

**grantTypes** `string[]` (default: \["authorization\_code", "refresh\_token"])

Supported grant types.

**extraAuthorizeParams** `Record\<string, string\>`

Extra parameters added to authorize requests, e.g. `{ access_type: "offline", prompt: "consent" }`.

**getUserInfo** `(payload) =\> UserInfo`

Custom extractor for user info from the verified payload. Defaults to standard OIDC claims.

**Signature**

```ts wrap theme={null}
interface OAuthProxyConfig {
  authEndpoint: string;
  tokenEndpoint: string;
  issuer: string;
  verifyToken: VerifyToken;
  clientId: string;
  clientSecret?: string;
  scopes?: string[];
  grantTypes?: string[];
  extraAuthorizeParams?: Record<string, string>;
  getUserInfo?: (payload: Record<string, unknown>) => UserInfo;
}
```

### OAuthProxyOptions

Options for `mountOAuthProxy`.

```ts theme={null}
import type { OAuthProxyOptions } from "mcp-use/server";
```

Options for configuring the fail-closed Hono OAuth BFF routes mounted by `mountOAuthProxy`. Cross-origin access and loopback targets are disabled by default. `authenticate` and `validateServerUrl` may return a boolean or a promise.

**Properties**

> **basePath** `string` (default: /oauth)
>
> &#x20;
>
> Base path for the proxy routes.&#x20;
>
> **enableLogging** `boolean` (default: true)
>
> &#x20;
>
> Enable request logging to the console.&#x20;
>
> **allowedOrigins** `readonly string[]` (default: \[])
>
> &#x20;
>
> Browser origins allowed to call the BFF cross-origin. Same-origin calls are
> implicit.&#x20;
>
> **allowLoopback** `boolean` (default: false)
>
> &#x20;
>
> Permit HTTP(S) loopback targets for explicit local development.&#x20;
>
> **timeoutMs** `number` (default: 10000)
>
> &#x20;
>
> Upstream request timeout.&#x20;
>
> **maxRequestBodyBytes** `number` (default: 65536)
>
> &#x20;
>
> Maximum BFF and OAuth endpoint request body size.&#x20;
>
> **maxResponseBodyBytes** `number` (default: 1048576)
>
> &#x20;
>
> Maximum upstream response body size.&#x20;
>
> **authenticate** `(c: Context) =\> Promise\<boolean\> | boolean`
>
> &#x20;
>
> Optional request authentication. Return `false` to reject with 401.&#x20;
>
> **validateServerUrl** `(serverUrl: string, c: Context) =\> Promise\<boolean\> | boolean`
>
> &#x20;
>
> Optional deployment-specific allowlist for logical MCP server URLs. Return
> `false` to reject with 403.&#x20;

**Signature**

```ts wrap theme={null}
interface OAuthProxyOptions {
  basePath?: string;
  allowedOrigins?: readonly string[];
  allowLoopback?: boolean;
  timeoutMs?: number;
  maxRequestBodyBytes?: number;
  maxResponseBodyBytes?: number;
  enableLogging?: boolean;
  authenticate?: (c: Context) => Promise<boolean> | boolean;
  validateServerUrl?: (
    serverUrl: string,
    c: Context,
  ) => Promise<boolean> | boolean;
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.