> ## Documentation Index
> Fetch the complete documentation index at: https://openmetadata-fix-mcp-oauth-security-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth 2.0 Authentication for MCP Server

> Connect to OpenMetadata's MCP Server using OAuth 2.0 with your existing SSO provider. No Personal Access Tokens required.

# 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 |

<Note>
  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.
</Note>

## How It Works

Connecting via OAuth is simple:

1. **Add your OpenMetadata MCP Server URL** in your AI client (e.g., `https://your-openmetadata-instance.com/mcp`)
2. **A browser window opens** prompting you to sign in with your usual OpenMetadata credentials
3. **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.

<CardGroup cols={2}>
  <Card title="Google SSO" href="/v2.0.x-SNAPSHOT/deployment/security/google">
    Sign in with your Google Workspace account.
  </Card>

  <Card title="Azure AD SSO" href="/v2.0.x-SNAPSHOT/deployment/security/azure">
    Sign in with your Microsoft / Azure AD account.
  </Card>

  <Card title="Okta SSO" href="/v2.0.x-SNAPSHOT/deployment/security/okta">
    Sign in with your Okta account.
  </Card>

  <Card title="Auth0 SSO" href="/v2.0.x-SNAPSHOT/deployment/security/auth0">
    Sign in with your Auth0 account.
  </Card>

  <Card title="Amazon Cognito" href="/v2.0.x-SNAPSHOT/deployment/security/amazon-cognito-sso">
    Sign in with Amazon Cognito.
  </Card>

  <Card title="Custom OIDC" href="/v2.0.x-SNAPSHOT/deployment/security/custom-oidc">
    Sign in with any OIDC-compatible provider.
  </Card>

  <Card title="SAML" href="/v2.0.x-SNAPSHOT/deployment/security/saml">
    Sign in with your SAML identity provider.
  </Card>

  <Card title="LDAP" href="/v2.0.x-SNAPSHOT/deployment/security/ldap">
    Sign in with your LDAP / Active Directory credentials.
  </Card>
</CardGroup>

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:

1. Navigate to **Settings** in your OpenMetadata instance
2. Go to the **SSO** configuration section
3. 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](/v2.0.x-SNAPSHOT/deployment/security).

## 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](#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:

<CardGroup cols={2}>
  <Card title="Claude Desktop" href="/v2.0.x-SNAPSHOT/how-to-guides/mcp/claude">
    Connect via Anthropic's AI assistant.
  </Card>

  <Card title="Cursor" href="/v2.0.x-SNAPSHOT/how-to-guides/mcp/cursor">
    Connect via Cursor IDE.
  </Card>

  <Card title="VS Code" href="/v2.0.x-SNAPSHOT/how-to-guides/mcp/vscode">
    Connect via Visual Studio Code.
  </Card>

  <Card title="Claude Code" href="/v2.0.x-SNAPSHOT/how-to-guides/mcp/claude-code">
    Connect via Claude Code CLI.
  </Card>

  <Card title="Goose" href="/v2.0.x-SNAPSHOT/how-to-guides/mcp/goose">
    Connect via Block's open-source AI agent.
  </Card>
</CardGroup>

## 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:

1. The MCP client fetches OpenMetadata's OAuth discovery document at `/.well-known/oauth-authorization-server` to learn the authorization, token, and registration endpoints.
2. 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.
3. 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.
4. After you sign in, OpenMetadata redirects back to the client with an authorization code.
5. The client exchanges the code for an access token and a refresh token.
6. 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](#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](https://datatracker.ietf.org/doc/html/rfc7009)), 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](#how-the-connection-works-under-the-hood). Authenticate using either method:

**HTTP Basic authentication** (client credentials in the `Authorization` header):

```http theme={null}
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):

```http theme={null}
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`.