Zum Hauptinhalt springen

Generic OAuth 2.0 / OIDC

This guide covers general configuration steps for OAuth 2.0 and OpenID Connect providers. Since OIDC is built on top of OAuth 2.0, both follow similar steps.

tipp

Check our Provider List to see if your specific provider has been tested with MCP Auth.

Get issuer URL​

The issuer URL (also called authorization server URL or base URL) is required for MCP Auth configuration. To find it:

  1. Check your provider's documentation for the authorization server URL
  2. Some providers expose this at https://{your-domain}/.well-known/oauth-authorization-server
  3. For OIDC providers, try https://{your-domain}/.well-known/openid-configuration
  4. Look in your provider's admin console under OAuth/API settings

Configure scopes​

You'll need to define scopes in your authorization server that represent the permissions your MCP server needs:

  1. Define scopes in your authorization server, e.g.:

    • create:todos
    • read:todos
    • delete:todos

  2. Assign scopes to users using your provider's interface

    • Some providers support role-based management
    • Others use direct scope assignments

Check your provider's documentation for specific instructions on scope management.

Retrieving user identity​

OIDC providers​

Most OpenID Connect providers support the userinfo endpoint to retrieve user identity information.

Check your provider's documentation to see if it supports this endpoint. If your provider supports OpenID Connect Discovery, you can also check if the userinfo_endpoint is included in the discovery document (response from the .well-known/openid-configuration endpoint).

To fetch an access token that can be used to access the userinfo endpoint, at least two scopes are required: openid and profile. Check your provider's documentation to see the mapping of scopes to user identity claims.

OAuth 2.0 providers​

While OAuth 2.0 does not define a standard way to retrieve user identity information, many providers implement their own endpoints to do so. Check your provider's documentation to see how to retrieve user identity information using an access token and what parameters are required to fetch such access token when invoking the authorization flow.

Token request parameters​

Different authorization servers use various approaches for specifying the target resource:

Resource indicator based​

Uses the resource parameter (RFC 8707):

{
  "resource": "http://localhost:3001/",
  "scope": "create:todos read:todos"
}

Audience based​

Uses the audience parameter:

{
  "audience": "todo-api",
  "scope": "create:todos read:todos"
}

Pure scope based​

Relies solely on scopes (traditional OAuth 2.0):

{
  "scope": "todo-api:create todo-api:read openid profile"
}

Check your provider's documentation for supported parameters.

Register MCP client​

If your provider supports Dynamic Client Registration or OAuth Client ID Metadata Document, you may skip manual registration. Otherwise:

  1. Sign in to your provider's console
  2. Navigate to "Applications" or "Clients" section
  3. Create a new application/client
  4. Select "Native App" or "Public client" if required
  5. Configure the redirect URIs. For VS Code: 
    http://127.0.0.1
https://vscode.dev/redirect
  6. Configure the required scopes/permissions
  7. Copy the "Client ID" or "Application ID" for use in your MCP client