OAuth 2.0 Authentication for MCP Server

OpenMetadata’s MCP Server supports OAuth 2.0 authentication, allowing you to connect AI assistants like Claude, Cursor, and VS Code directly using your existing OpenMetadata login. This is the same way you sign in to the OpenMetadata UI. No need to generate, copy, or rotate Personal Access Tokens.

Why OAuth 2.0?

	Personal Access Token (PAT)	OAuth 2.0
Setup	Generate token, copy into config	Enter server URL, sign in via browser
Security	Token stored in plain text config files	No secrets stored locally
Expiration	Manual rotation when token expires	Tokens refresh automatically
Access	Must generate and manage tokens per user	Uses your existing OpenMetadata login

OAuth 2.0 is the recommended way to connect MCP clients. PAT-based authentication remains supported for backward compatibility and environments where browser-based login is not available.

How It Works

Connecting via OAuth is simple:

Add your OpenMetadata MCP Server URL in your AI client (e.g., https://your-openmetadata-instance.com/mcp)
A browser window opens prompting you to sign in with your usual OpenMetadata credentials
You’re connected and tokens are managed automatically in the background

That’s it. Your MCP client handles the rest, including refreshing your session when needed.

Supported Authentication Methods

The MCP Server inherits the authentication method configured for your OpenMetadata instance. Whatever SSO provider your organization uses to sign in to OpenMetadata will also be used for MCP connections.

Google SSO

Azure AD SSO

Okta SSO

Auth0 SSO

Amazon Cognito

Custom OIDC

SAML

LDAP

If your instance uses basic authentication (username and password), you will see a login form where you can enter your OpenMetadata credentials directly.

Changing Your Authentication Method

The MCP Server automatically uses the same authentication method configured for your OpenMetadata instance. To change how users authenticate:

Navigate to Settings in your OpenMetadata instance
Go to the SSO configuration section
Update the authentication provider (e.g., switch from basic auth to Google SSO)

Once updated, all MCP client connections will use the new authentication method with no changes needed on the client side. For detailed instructions on configuring each SSO provider, see the Security documentation.

Token Management

OAuth tokens are handled entirely by your MCP client with no manual management needed:

Access tokens are short-lived and automatically refreshed in the background
Sessions stay active as long as you’re using the MCP client regularly
Re-authentication is only needed if your refresh token expires after an extended period of inactivity (30 days)

To revoke access for an MCP client, use the OAuth 2.0 Token Revocation endpoint described under Revoking Access below.

Security

OpenMetadata’s MCP OAuth implementation follows industry-standard security practices:

PKCE (Proof Key for Code Exchange): Protects the authorization flow against interception attacks, even on desktop and CLI clients
Encrypted token storage: All tokens are encrypted at rest in the OpenMetadata database
Short-lived access tokens: Access tokens expire quickly, limiting exposure if compromised
Automatic token refresh: Clients seamlessly refresh tokens without user interaction
Rate limiting: Built-in protection against brute-force and abuse
No secrets in config files: Unlike PAT-based auth, OAuth does not require storing any secrets on your local machine

Supported MCP Clients

Set up OAuth authentication with your preferred MCP client:

Claude Desktop

Connect via Anthropic’s AI assistant.

Cursor

Connect via Cursor IDE.

VS Code

Connect via Visual Studio Code.

Claude Code

Connect via Claude Code CLI.

Goose

Connect via Block’s open-source AI agent.

How the Connection Works (Under the Hood)

OpenMetadata’s MCP OAuth implementation uses OAuth 2.0 Dynamic Client Registration (RFC 7591), so MCP clients connect without any manual app setup:

The MCP client fetches OpenMetadata’s OAuth discovery document at /.well-known/oauth-authorization-server to learn the authorization, token, and registration endpoints.
The client automatically registers itself by posting its metadata to the registration endpoint. OpenMetadata issues a client_id in response — no admin action is required.
The client initiates an Authorization Code flow with PKCE (SHA-256), opening your browser to sign in via your configured SSO provider or basic auth.
After you sign in, OpenMetadata redirects back to the client with an authorization code.
The client exchanges the code for an access token and a refresh token.
All subsequent MCP tool calls include the access token. When it expires, the client uses the refresh token to get a new one silently.

Discovery Endpoints

Endpoint	Purpose
`GET /.well-known/oauth-authorization-server`	OAuth 2.0 authorization server metadata (RFC 8414)
`GET /.well-known/openid-configuration`	OAuth metadata compatibility alias — serves the same RFC 8414 metadata as above for clients that only check this OIDC-conventional path (not a true OpenID Connect discovery document)
`POST /mcp/register`	Dynamic client registration

Token Lifetimes

OAuth tokens are handled entirely by your MCP client with no manual management needed.

Token type	Lifetime	Notes
Access token	10 minutes	Short-lived to limit exposure. Automatically refreshed by the client
Authorization code	10 minutes	Single-use. Expires if the login flow stalls
Refresh token	30 days	Grants new access tokens without re-authentication. Expires after 30 days of inactivity

Re-authentication is only required when the refresh token expires (30-day inactivity window). To revoke access for an MCP client, use the OAuth 2.0 Token Revocation endpoint described under Revoking Access below.

Rate Limits

The MCP OAuth endpoints are rate-limited per IP address to prevent abuse:

Endpoint	Limit
`/mcp/register` (client registration)	10 requests per hour
`/mcp/token` (token requests)	30 requests per minute

These limits are per-server-instance. In clustered deployments, the effective limit is multiplied by the number of instances.

Allowed Origins (CORS)

By default, the MCP Server allows CORS requests only from a small set of local development origins (http://localhost:3000, http://localhost:8585, http://localhost:9090) — it does not allow all origins. This allowlist is part of OpenMetadata’s MCP settings, stored in the database rather than the static server configuration file. Update it from the MCP application’s configuration page (<YOUR-OpenMetadata-SERVER>/marketplace/apps/McpApplication) or via the GET/PUT /api/v1/system/mcp/config API (admin only). Only requests whose Origin header exactly matches an entry in the allowlist receive a valid Access-Control-Allow-Origin response header — there is no wildcard or prefix matching. This is relevant for browser-based MCP clients or custom integrations that call the MCP endpoint directly from a web page.

Revoking Access

MCP clients can revoke an access or refresh token directly using the OAuth 2.0 Token Revocation endpoint (RFC 7009), advertised as revocation_endpoint in the OAuth discovery document. A POST request to {baseUrl}/mcp/revoke invalidates the token immediately. There is currently no separate admin-side option to revoke an MCP client’s access. Revocation is a client-initiated action using its registered credentials. The revocation endpoint requires client authentication before it processes the request, using the client_id and client_secret issued during Dynamic Client Registration. Authenticate using either method: HTTP Basic authentication (client credentials in the Authorization header):

POST {baseUrl}/mcp/revoke
Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

token=<token>&token_type_hint=access_token

Form-based authentication (client credentials in the request body):

POST {baseUrl}/mcp/revoke
Content-Type: application/x-www-form-urlencoded

token=<token>&token_type_hint=access_token&client_id=<client_id>&client_secret=<client_secret>

token_type_hint is optional and can be access_token or refresh_token. A request without valid client credentials returns invalid_client.

​OAuth 2.0 Authentication for MCP Server

​Why OAuth 2.0?

​How It Works

​Supported Authentication Methods

Google SSO

Azure AD SSO

Okta SSO

Auth0 SSO

Amazon Cognito

Custom OIDC

SAML

LDAP

​Changing Your Authentication Method

​Token Management

​Security

​Supported MCP Clients

Claude Desktop

Cursor

VS Code

Claude Code

Goose

​How the Connection Works (Under the Hood)

​Discovery Endpoints

​Token Lifetimes

​Rate Limits

​Allowed Origins (CORS)

​Revoking Access

OAuth 2.0 Authentication for MCP Server

Why OAuth 2.0?

How It Works

Supported Authentication Methods

Changing Your Authentication Method

Token Management

Security

Supported MCP Clients

How the Connection Works (Under the Hood)

Discovery Endpoints

Token Lifetimes

Rate Limits

Allowed Origins (CORS)

Revoking Access