Class OAuthManager

Main orchestrator for OAuth 2.1 flows in MCP connections.

Coordinates all OAuth operations including:

Authorization server metadata discovery
Dynamic client registration (DCR)
Authorization code flow with PKCE
Token storage and refresh

Example

const oauth = new OAuthManager();

// Try to get an access token (may throw OAuthAuthorizationRequiredError)
try {
    const accessToken = await oauth.getAccessToken(connectionId, serverConfig, contextUser);
    // Use access token for API calls
} catch (error) {
    if (error instanceof OAuthAuthorizationRequiredError) {
        // Redirect user to error.authorizationUrl
    }
}

Index

Constructors

constructor

Methods

clearExpiredAuthorizationStates completeAuthorizationFlow getAccessToken getConnectionStatus handleAuthorizationError initiateAuthorizationFlow markRequiresReauthorization validateOAuthConfiguration

Constructors

constructor

new OAuthManager(): OAuthManager
Returns OAuthManager
- Defined in packages/AI/MCPClient/src/oauth/OAuthManager.ts:76

Methods

clearExpiredAuthorizationStates

clearExpiredAuthorizationStates(
contextUser: UserInfo,
provider?: IMetadataProvider,
): Promise<number>
Clears expired authorization states for cleanup.
Parameters
- contextUser: UserInfo
  User context
- Optionalprovider: IMetadataProvider
Returns Promise<number>
Number of states cleared
- Defined in packages/AI/MCPClient/src/oauth/OAuthManager.ts:620

completeAuthorizationFlow

completeAuthorizationFlow(
    stateParameter: string,
    code: string,
    contextUser: UserInfo,
): Promise<CompleteAuthorizationResult>
Completes an OAuth authorization flow by exchanging the code for tokens.

Called by the OAuth callback handler after user consent.
Parameters
- stateParameter: string
  The state parameter from the callback
- code: string
  The authorization code
- contextUser: UserInfo
  User context
Returns Promise<CompleteAuthorizationResult>
Completion result
- Defined in packages/AI/MCPClient/src/oauth/OAuthManager.ts:339

getAccessToken

getAccessToken(
    connectionId: string,
    serverId: string,
    oauthConfig: MCPServerOAuthConfig,
    publicUrl: string,
    contextUser: UserInfo,
): Promise<string>
Gets a valid access token for an OAuth-protected connection.

If valid tokens exist, returns the access token. If tokens are expired but refresh token is valid, refreshes and returns. If no valid tokens, throws OAuthAuthorizationRequiredError with authorization URL.
Parameters
- connectionId: string
  MCP Server Connection ID
- serverId: string
  MCP Server ID
- oauthConfig: MCPServerOAuthConfig
  OAuth configuration from MCP Server
- publicUrl: string
  MJAPI public URL for callbacks
- contextUser: UserInfo
  User context
Returns Promise<string>
Valid access token

Throws
OAuthAuthorizationRequiredError if user authorization is needed

Throws
OAuthReauthorizationRequiredError if refresh failed and re-auth is needed
- Defined in packages/AI/MCPClient/src/oauth/OAuthManager.ts:99

getConnectionStatus

getConnectionStatus(
    connectionId: string,
    oauthConfig: MCPServerOAuthConfig,
    contextUser: UserInfo,
): Promise<OAuthConnectionStatus>
Gets the OAuth connection status.
Parameters
- connectionId: string
  MCP Server Connection ID
- oauthConfig: MCPServerOAuthConfig
  OAuth configuration
- contextUser: UserInfo
  User context
Returns Promise<OAuthConnectionStatus>
Connection status
- Defined in packages/AI/MCPClient/src/oauth/OAuthManager.ts:506

handleAuthorizationError

handleAuthorizationError(
    stateParameter: string,
    errorCode: string,
    errorDescription: string,
    contextUser: UserInfo,
): Promise<void>
Handles an OAuth callback error.
Parameters
- stateParameter: string
  The state parameter
- errorCode: string
  OAuth error code
- errorDescription: string
  Error description
- contextUser: UserInfo
  User context
Returns Promise<void>
- Defined in packages/AI/MCPClient/src/oauth/OAuthManager.ts:476

initiateAuthorizationFlow

initiateAuthorizationFlow(
    connectionId: string,
    serverId: string,
    oauthConfig: MCPServerOAuthConfig,
    publicUrl: string,
    contextUser: UserInfo,
    options?: { frontendCallbackUrl?: string; frontendReturnUrl?: string },
): Promise<InitiateAuthorizationResult>
Initiates an OAuth authorization flow.

Creates authorization URL with PKCE and stores state in database. The user should be redirected to the returned URL to complete consent.
Parameters
- connectionId: string
  MCP Server Connection ID
- serverId: string
  MCP Server ID
- oauthConfig: MCPServerOAuthConfig
  OAuth configuration
- publicUrl: string
  MJAPI public URL for callbacks
- contextUser: UserInfo
  User context
- Optionaloptions: { frontendCallbackUrl?: string; frontendReturnUrl?: string }
  Additional options
  - OptionalfrontendCallbackUrl?: string
    URL to use as redirect_uri (frontend handles the callback)
  - OptionalfrontendReturnUrl?: string
    URL to redirect to after OAuth completion
Returns Promise<InitiateAuthorizationResult>
Authorization initiation result with URL
- Defined in packages/AI/MCPClient/src/oauth/OAuthManager.ts:217

markRequiresReauthorization

markRequiresReauthorization(
    connectionId: string,
    reason: string,
    contextUser: UserInfo,
): Promise<void>
Marks a connection as requiring re-authorization.

Clears stored tokens and returns a message for the user.
Parameters
- connectionId: string
  MCP Server Connection ID
- reason: string
  Reason for re-authorization
- contextUser: UserInfo
  User context
Returns Promise<void>
- Defined in packages/AI/MCPClient/src/oauth/OAuthManager.ts:601

validateOAuthConfiguration

validateOAuthConfiguration(
oauthConfig: MCPServerOAuthConfig,
contextUser: UserInfo,
): Promise<{ error?: string; valid: boolean }>
Validates OAuth configuration for an MCP server.
Parameters
- oauthConfig: MCPServerOAuthConfig
  OAuth configuration to validate
- contextUser: UserInfo
  User context
Returns Promise<{ error?: string; valid: boolean }>
Validation result
- Defined in packages/AI/MCPClient/src/oauth/OAuthManager.ts:550

Class OAuthManager

Example

Index

Constructors

Methods

Constructors

constructor

Returns OAuthManager

Methods

clearExpiredAuthorizationStates

Parameters

Returns Promise<number>

completeAuthorizationFlow

Parameters

Returns Promise<CompleteAuthorizationResult>

getAccessToken

Parameters

Returns Promise<string>

Throws

Throws

getConnectionStatus

Parameters

Returns Promise<OAuthConnectionStatus>

handleAuthorizationError

Parameters

Returns Promise<void>

initiateAuthorizationFlow

Parameters

`Optional`frontendCallbackUrl?: string

`Optional`frontendReturnUrl?: string

Returns Promise<InitiateAuthorizationResult>

markRequiresReauthorization

Parameters

Returns Promise<void>

validateOAuthConfiguration

Parameters

Returns Promise<{ error?: string; valid: boolean }>

Settings

On This Page

Class OAuthManager

Example

Index

Constructors

Methods

Constructors

constructor

Returns OAuthManager

Methods

clearExpiredAuthorizationStates

Parameters

Returns Promise<number>

completeAuthorizationFlow

Parameters

Returns Promise<CompleteAuthorizationResult>

getAccessToken

Parameters

Returns Promise<string>

Throws

Throws

getConnectionStatus

Parameters

Returns Promise<OAuthConnectionStatus>

handleAuthorizationError

Parameters

Returns Promise<void>

initiateAuthorizationFlow

Parameters

OptionalfrontendCallbackUrl?: string

OptionalfrontendReturnUrl?: string

Returns Promise<InitiateAuthorizationResult>

markRequiresReauthorization

Parameters

Returns Promise<void>

validateOAuthConfiguration

Parameters

Returns Promise<{ error?: string; valid: boolean }>

Settings

On This Page

`Optional`frontendCallbackUrl?: string

`Optional`frontendReturnUrl?: string