Configure MCP Auth in MCP server

To connect your MCP server to an OAuth 2.1 or OpenID Connect provider, you need to configure the MCP Auth instance. This involves initializing the instance with your provider's authorization server metadata and setting up the necessary authorization flows.

Init MCP Auth

Automatic metadata fetching

The easiest way to initialize the MCP Auth instance is by using the built-in functions that fetch the metadata from a well-known URL. If your provider conforms to one of the following standards:

• OAuth 2.0 Authorization Server Metadata
• OpenID Connect Discovery

You can use the fetchServerConfig to automatically retrieve the metadata by providing the issuer URL:

Python

from mcpauth import MCPAuth
from mcpauth.config import AuthServerType, fetch_server_config

mcp_auth = MCPAuth(
    server=fetch_server_config(
        '<auth-server-url>',
        type=AuthServerType.OIDC  # or AuthServerType.OAUTH
    )
)

Node.js

import { MCPAuth, fetchServerConfig } from 'mcp-auth';
const mcpAuth = new MCPAuth({
  server: await fetchServerConfig('<auth-server-issuer>', { type: 'oidc' }), // or 'oauth'
});

If your issuer includes a path, the behavior differs slightly between OAuth 2.0 and OpenID Connect:

• OAuth 2.0: The well-known URL is appended to the domain of the issuer. For example, if your issuer is https://my-project.logto.app/oauth, the well-known URL will be https://auth.logto.io/.well-known/oauth-authorization-server/oauth.
• OpenID Connect: The well-known URL is appended directly to the issuer. For example, if your issuer is https://my-project.logto.app/oidc, the well-known URL will be https://auth.logto.io/oidc/.well-known/openid-configuration.

Other ways to initialize MCP Auth

Custom data transpilation

In some cases, the metadata returned by the provider may not conform to the expected format. If you are confident that the provider is compliant, you can use the transpile_data option to modify the metadata before it is used:

Python

from mcpauth import MCPAuth
from mcpauth.config import AuthServerType
from mcpauth.utils import fetch_server_config

mcp_auth = MCPAuth(
    server=fetch_server_config(
        '<auth-server-url>',
        type=AuthServerType.OIDC,
        transpile_data=lambda data: {**data, 'response_types_supported': ['code']} 
    )
)

Node.js

import { MCPAuth, fetchServerConfig } from 'mcp-auth';
const mcpAuth = new MCPAuth({
  server: await fetchServerConfig('<auth-server-issuer>', {
    type: 'oidc',
    transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), 
  }),
});

This allows you to modify the metadata object before it is used by MCP Auth. For example, you can add or remove fields, change their values, or convert them to a different format.

Fetch metadata from a specific URL

If your provider has a specific metadata URL rather than the standard ones, you can use it similarly:

Python

from mcpauth import MCPAuth
from mcpauth.config import AuthServerType
from mcpauth.utils import fetch_server_config_by_well_known_url

mcp_auth = MCPAuth(
    server=fetch_server_config_by_well_known_url(
        '<metadata-url>', 
        type=AuthServerType.OIDC # or AuthServerType.OAUTH
    )
)

Node.js

import { MCPAuth, fetchServerConfigByWellKnownUrl } from 'mcp-auth';

const mcpAuth = new MCPAuth({
  server: await fetchServerConfigByWellKnownUrl('<metadata-url>', { type: 'oidc' }), // or 'oauth'
});

Fetch metadata from a specific URL with custom data transpilation

In some cases, the provider response may be malformed or not conforming to the expected metadata format. If you are confident that the provider is compliant, you can transpile the metadata via the config option:

Python

from mcpauth import MCPAuth
from mcpauth.config import AuthServerType, fetch_server_config_by_well_known_url

mcp_auth = MCPAuth(
    server=fetch_server_config_by_well_known_url(
        '<metadata-url>',
        type=AuthServerType.OIDC,
        transpile_data=lambda data: {**data, 'response_types_supported': ['code']} 
    )
)

Node.js

const mcpAuth = new MCPAuth({
  server: await fetchServerConfigByWellKnownUrl('<metadata-url>', {
    type: 'oidc',
    transpileData: (data) => ({ ...data, response_types_supported: ['code'] }), 
  }),
});

Manually provide metadata

If your provider does not support metadata fetching, you can manually provide the metadata object:

Python

from mcpauth import MCPAuth
from mcpauth.config import AuthServerConfig, AuthServerType, AuthorizationServerMetadata

mcp_auth = MCPAuth(
    server=AuthServerConfig(
        type=AuthServerType.OIDC,  # or AuthServerType.OAUTH
        metadata=AuthorizationServerMetadata(
            issuer='<issuer-url>',
            authorization_endpoint='<authorization-endpoint-url>',
            # ... other metadata fields
        ),
    )
)       

Node.js

const mcpAuth = new MCPAuth({
  server: {
    metadata: {
      issuer: '<issuer-url>',
      // Metadata fields should be camelCase
      authorizationEndpoint: '<authorization-endpoint-url>',
      // ... other metadata fields
    },
    type: 'oidc', // or 'oauth'
  },
});