MCP TypeScript SDK (V2)
    Preparing search index...

    Interface OAuthClientProvider

    Implements an end-to-end OAuth client to be used with one MCP server.

    This client relies upon a concept of an authorized "session," the exact meaning of which is application-defined. Tokens, authorization codes, and code verifiers should not cross different sessions.

    Transports accept OAuthClientProvider directly via the authProvider option — they adapt it to AuthProvider internally via adaptOAuthProvider. No changes are needed to existing implementations.

    interface OAuthClientProvider {
        addClientAuthentication?: AddClientAuthentication;
        clientMetadataUrl?: string;
        get clientMetadata(): {
            client_name?: string;
            client_uri?: string;
            contacts?: string[];
            grant_types?: string[];
            jwks?: any;
            jwks_uri?: string;
            logo_uri?: string;
            policy_uri?: string;
            redirect_uris: string[];
            response_types?: string[];
            scope?: string;
            software_id?: string;
            software_statement?: string;
            software_version?: string;
            token_endpoint_auth_method?: string;
            tos_uri?: string;
        };
        get redirectUrl(): string | URL | undefined;
        authorizationServerUrl?(): string | Promise<string | undefined> | undefined;
        clientInformation(): | OAuthClientInformationMixed
        | Promise<(OAuthClientInformationMixed | undefined)>
        | undefined;
        codeVerifier(): string | Promise<string>;
        discoveryState?(): | OAuthDiscoveryState
        | Promise<OAuthDiscoveryState | undefined>
        | undefined;
        invalidateCredentials?(
            scope: "all" | "client" | "tokens" | "verifier" | "discovery",
        ): void | Promise<void>;
        prepareTokenRequest?(
            scope?: string,
        ): URLSearchParams | Promise<URLSearchParams | undefined> | undefined;
        redirectToAuthorization(authorizationUrl: URL): void | Promise<void>;
        resourceUrl?(): string | Promise<string | undefined> | undefined;
        saveAuthorizationServerUrl?(
            authorizationServerUrl: string,
        ): void | Promise<void>;
        saveClientInformation?(
            clientInformation: OAuthClientInformationMixed,
        ): void | Promise<void>;
        saveCodeVerifier(codeVerifier: string): void | Promise<void>;
        saveDiscoveryState?(state: OAuthDiscoveryState): void | Promise<void>;
        saveResourceUrl?(resourceUrl: string): void | Promise<void>;
        saveTokens(
            tokens: {
                access_token: string;
                expires_in?: number;
                id_token?: string;
                refresh_token?: string;
                scope?: string;
                token_type: string;
            },
        ): void
        | Promise<void>;
        state?(): string | Promise<string>;
        tokens(): | {
            access_token: string;
            expires_in?: number;
            id_token?: string;
            refresh_token?: string;
            scope?: string;
            token_type: string;
        }
        | Promise<
            | {
                access_token: string;
                expires_in?: number;
                id_token?: string;
                refresh_token?: string;
                scope?: string;
                token_type: string;
            }
            | undefined,
        >
        | undefined;
        validateResourceURL?(
            serverUrl: string | URL,
            resource?: string,
        ): Promise<URL | undefined>;
    }

    Implemented by

    Index

    Properties

    addClientAuthentication? clientMetadataUrl?

    Accessors

    clientMetadata redirectUrl

    Methods

    authorizationServerUrl? clientInformation codeVerifier discoveryState? invalidateCredentials? prepareTokenRequest? redirectToAuthorization resourceUrl? saveAuthorizationServerUrl? saveClientInformation? saveCodeVerifier saveDiscoveryState? saveResourceUrl? saveTokens state? tokens validateResourceURL?

    Properties

    addClientAuthentication?: AddClientAuthentication

    Adds custom client authentication to OAuth token requests.

    This optional method allows implementations to customize how client credentials are included in token exchange and refresh requests. When provided, this method is called instead of the default authentication logic, giving full control over the authentication mechanism.

    Common use cases include:

    • Supporting authentication methods beyond the standard OAuth 2.0 methods
    • Adding custom headers for proprietary authentication schemes
    • Implementing client assertion-based authentication (e.g., JWT bearer tokens)

    The request headers (can be modified to add authentication)

    The request body parameters (can be modified to add credentials)

    The token endpoint URL being called

    Optional OAuth metadata for the server, which may include supported authentication methods

    clientMetadataUrl?: string

    External URL the server should use to fetch client metadata document

    Accessors

    • get clientMetadata(): {
          client_name?: string;
          client_uri?: string;
          contacts?: string[];
          grant_types?: string[];
          jwks?: any;
          jwks_uri?: string;
          logo_uri?: string;
          policy_uri?: string;
          redirect_uris: string[];
          response_types?: string[];
          scope?: string;
          software_id?: string;
          software_statement?: string;
          software_version?: string;
          token_endpoint_auth_method?: string;
          tos_uri?: string;
      }

      Metadata about this OAuth client.

      Returns {
          client_name?: string;
          client_uri?: string;
          contacts?: string[];
          grant_types?: string[];
          jwks?: any;
          jwks_uri?: string;
          logo_uri?: string;
          policy_uri?: string;
          redirect_uris: string[];
          response_types?: string[];
          scope?: string;
          software_id?: string;
          software_statement?: string;
          software_version?: string;
          token_endpoint_auth_method?: string;
          tos_uri?: string;
      }

    • get redirectUrl(): string | URL | undefined

      The URL to redirect the user agent to after authorization. Return undefined for non-interactive flows that don't require user interaction (e.g., client_credentials, jwt-bearer).

      Returns string | URL | undefined

    Methods

    • Returns the previously saved authorization server URL, if available.

      Providers implementing Cross-App Access can use this to access the authorization server URL discovered during the OAuth flow.

      Returns string | Promise<string | undefined> | undefined

      The authorization server URL, or undefined if not available

    • Loads the PKCE code verifier for the current session, necessary to validate the authorization result.

      Returns string | Promise<string>

    • If implemented, provides a way for the client to invalidate (e.g. delete) the specified credentials, in the case where the server has indicated that they are no longer valid. This avoids requiring the user to intervene manually.

      Parameters

      • scope: "all" | "client" | "tokens" | "verifier" | "discovery"

      Returns void | Promise<void>

    • Prepares grant-specific parameters for a token request.

      This optional method allows providers to customize the token request based on the grant type they support. When implemented, it returns the grant type and any grant-specific parameters needed for the token exchange.

      If not implemented, the default behavior depends on the flow:

      • For authorization code flow: uses code, code_verifier, and redirect_uri
      • For client_credentials: detected via grant_types in clientMetadata

      Parameters

      • Optionalscope: string

        Optional scope to request

      Returns URLSearchParams | Promise<URLSearchParams | undefined> | undefined

      Grant type and parameters, or undefined to use default behavior

      // For client_credentials grant:
      prepareTokenRequest(scope) {
        return {
          grantType: 'client_credentials',
          params: scope ? { scope } : {}
        };
      }

      // For authorization_code grant (default behavior):
      async prepareTokenRequest() {
        return {
          grantType: 'authorization_code',
          params: {
            code: this.authorizationCode,
            code_verifier: await this.codeVerifier(),
            redirect_uri: String(this.redirectUrl)
          }
        };
      }

    • Invoked to redirect the user agent to the given URL to begin the authorization flow.

      Parameters

      • authorizationUrl: URL

      Returns void | Promise<void>

    • Returns the previously saved resource URL, if available.

      Providers implementing Cross-App Access can use this to access the resource URL discovered during the OAuth flow.

      Returns string | Promise<string | undefined> | undefined

      The resource URL, or undefined if not available

    • Saves the authorization server URL after RFC 9728 discovery. This method is called by auth after successful discovery of the authorization server via protected resource metadata.

      Providers implementing Cross-App Access or other flows that need access to the discovered authorization server URL should implement this method.

      Parameters

      • authorizationServerUrl: string

        The authorization server URL discovered via RFC 9728

      Returns void | Promise<void>

    • Saves a PKCE code verifier for the current session, before redirecting to the authorization flow.

      Parameters

      • codeVerifier: string

      Returns void | Promise<void>

    • Saves the OAuth discovery state after RFC 9728 and authorization server metadata discovery. Providers can persist this state to avoid redundant discovery requests on subsequent auth calls.

      This state can also be provided out-of-band (e.g., from a previous session or external configuration) to bootstrap the OAuth flow without discovery.

      Called by auth after successful discovery.

      Parameters

      Returns void | Promise<void>

    • Saves the resource URL after RFC 9728 discovery. This method is called by auth after successful discovery of the resource metadata.

      Providers implementing Cross-App Access or other flows that need access to the discovered resource URL should implement this method.

      Parameters

      • resourceUrl: string

        The resource URL discovered via RFC 9728

      Returns void | Promise<void>

    • Stores new OAuth tokens for the current session, after a successful authorization.

      Parameters

      • tokens: {
            access_token: string;
            expires_in?: number;
            id_token?: string;
            refresh_token?: string;
            scope?: string;
            token_type: string;
        }

      Returns void | Promise<void>

    • Loads any existing OAuth tokens for the current session, or returns undefined if there are no saved tokens.

      Returns
          | {
              access_token: string;
              expires_in?: number;
              id_token?: string;
              refresh_token?: string;
              scope?: string;
              token_type: string;
          }
          | Promise<
              | {
                  access_token: string;
                  expires_in?: number;
                  id_token?: string;
                  refresh_token?: string;
                  scope?: string;
                  token_type: string;
              }
              | undefined,
          >
          | undefined

    • If defined, overrides the selection and validation of the RFC 8707 Resource Indicator. If left undefined, default validation behavior will be used.

      Implementations must verify the returned resource matches the MCP server.

      Parameters

      • serverUrl: string | URL
      • Optionalresource: string

      Returns Promise<URL | undefined>

    Settings

    Member Visibility

    On This Page

    Properties
    Accessors
    Methods