OAuth Proxy

Use oauthProxy when an identity provider cannot register MCP clients dynamically. You register one application in the provider dashboard, store its client credentials on the MCP server, and let the server mediate authorization and token exchange for MCP clients. If your provider supports Dynamic Client Registration, use a built-in provider or Custom Provider. In DCR mode, clients register directly with the upstream provider and the MCP server only verifies tokens. This guide covers the proxy workflow. Use the auth providers API reference for exact oauthProxy() options, defaults, payload contracts, and verifier behavior.

Use OAuth Proxy only when DCR is unavailable

OAuth Proxy is the right fit when all of these are true:

The provider gives you a fixed clientId and clientSecret.
The provider does not expose a registration_endpoint in OAuth metadata.
You can safely store the client secret on the MCP server.
You are comfortable with the MCP server brokering the OAuth callback and token exchange.

Common proxy targets include Google, GitHub, Okta, Microsoft Entra ID, and enterprise SSO deployments that require pre-registered applications.

Register one upstream redirect URI

In the provider dashboard, register the MCP server callback URL:

http://localhost:3000/oauth/callback

Use your deployed server domain in production:

https://mcp.example.com/oauth/callback

Do not register every MCP client’s redirect URI with the upstream provider. The MCP server brokers the callback for clients.

Configure the proxy

This Google example validates opaque user access tokens with Google’s tokeninfo and userinfo endpoints.

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

const server = new MCPServer({
  name: "google-proxy-server",
  version: "1.0.0",
  oauth: oauthProxy({
    authEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
    tokenEndpoint: "https://oauth2.googleapis.com/token",
    issuer: "https://accounts.google.com",
    clientId: process.env.GOOGLE_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    scopes: ["openid", "email", "profile"],
    extraAuthorizeParams: { access_type: "offline" },
    async verifyToken(token) {
      const tokenInfoResponse = await fetch(
        `https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=${encodeURIComponent(token)}`,
      );

      if (!tokenInfoResponse.ok) {
        throw new Error("Invalid Google access token");
      }

      const tokenInfo = (await tokenInfoResponse.json()) as Record<string, unknown>;

      if (tokenInfo.aud !== process.env.GOOGLE_CLIENT_ID) {
        throw new Error("Google token audience did not match this client");
      }

      const userInfoResponse = await fetch("https://openidconnect.googleapis.com/v1/userinfo", {
        headers: { Authorization: `Bearer ${token}` },
      });

      if (!userInfoResponse.ok) {
        throw new Error("Failed to fetch Google userinfo");
      }

      const userInfo = (await userInfoResponse.json()) as Record<string, unknown>;
      return { payload: { ...tokenInfo, ...userInfo } };
    },
  }),
});

await server.listen(3000);

Use jwksVerifier only for providers that issue JWT access tokens and publish a JWKS. Write a custom verifyToken function for opaque-token providers.

Understand the proxy flow

In proxy mode, the MCP server acts as the OAuth-facing server for MCP clients.

The MCP client calls the MCP server’s /register endpoint.
The MCP server returns the pre-registered upstream clientId.
The client starts PKCE authorization through the MCP server’s /authorize endpoint.
The upstream provider redirects to the MCP server’s /oauth/callback.
The MCP server forwards the authorization code to the client’s original redirect URI.
During token exchange, the MCP server injects the upstream clientId and clientSecret.
The client calls /mcp/* with the upstream access token.
The MCP server verifies the token with your verifyToken function.

The proxy passes upstream tokens through. It does not mint its own access tokens.

Handle opaque tokens

GitHub issues opaque access tokens, so jwksVerifier does not apply. Validate the token by calling the provider API.

oauth: oauthProxy({
  authEndpoint: "https://github.com/login/oauth/authorize",
  tokenEndpoint: "https://github.com/login/oauth/access_token",
  issuer: "https://github.com",
  clientId: process.env.GITHUB_CLIENT_ID!,
  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
  scopes: ["read:user", "user:email"],
  async verifyToken(token) {
    const response = await fetch("https://api.github.com/user", {
      headers: {
        Authorization: `Bearer ${token}`,
        "User-Agent": "my-mcp-server",
      },
    });

    if (!response.ok) {
      throw new Error("Invalid GitHub token");
    }

    const user = await response.json();
    return { payload: { sub: String(user.id), ...user } };
  },
  getUserInfo(payload) {
    return {
      userId: payload.sub as string,
      username: payload.login as string | undefined,
      name: payload.name as string | undefined,
      email: payload.email as string | undefined,
      picture: payload.avatar_url as string | undefined,
    };
  },
});

Use upstream tokens in tools

The upstream access token is available as ctx.auth.accessToken. Use it only when a tool must call the provider API on behalf of the user.

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

server.tool(
  {
    name: "get_google_profile",
    description: "Fetch the caller's Google profile.",
  },
  async (_args, ctx) => {
    if (!ctx.auth) {
      return error("Unauthorized");
    }

    const response = await fetch("https://openidconnect.googleapis.com/v1/userinfo", {
      headers: { Authorization: `Bearer ${ctx.auth.accessToken}` },
    });

    return object(await response.json());
  },
);

Next steps

Custom Provider

Use a provider that supports Dynamic Client Registration.

User Context

Use proxied identity data inside tools.

OAuth Proxy API reference

Look up exact proxy options, defaults, and verifier contracts.

PKCE

Review the authorization-code security flow used by MCP clients.

Get Started

MCP Server

MCP Apps

MCP Client

MCP Agent

Tooling

Use OAuth Proxy only when DCR is unavailable

Register one upstream redirect URI

Configure the proxy

Understand the proxy flow

Handle opaque tokens

Use upstream tokens in tools

Next steps

Custom Provider

User Context

OAuth Proxy API reference

PKCE

​Use OAuth Proxy only when DCR is unavailable

​Register one upstream redirect URI

​Configure the proxy

​Understand the proxy flow

​Handle opaque tokens

​Use upstream tokens in tools

​Next steps

Custom Provider

User Context

OAuth Proxy API reference

PKCE

Use OAuth Proxy only when DCR is unavailable

Register one upstream redirect URI

Configure the proxy

Understand the proxy flow

Handle opaque tokens

Use upstream tokens in tools

Next steps