> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maxicore.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate AI clients with OAuth 2.1 browser flow

> OAuth 2.1 is the recommended way to connect AI clients to Maxi AI Core. Paste your MCP URL, approve a browser consent screen, and you're connected.

OAuth 2.1 is the recommended way to connect AI clients to your WordPress site. You paste one URL into your AI client, a browser consent page opens, you click **Authorize**, and the client stores its token automatically. No application passwords, no manual token management — the client handles all future reconnections on its own.

## Your MCP endpoint URL

Every Maxi AI Core installation exposes a single MCP endpoint:

```text theme={null}
https://yoursite.com/wp-json/mcp/mcp-adapter-default-server
```

Replace `yoursite.com` with your actual domain. You can copy this URL directly from **Settings → AI Connections → Settings** using the copy button.

## Connecting a client

<Steps>
  <Step title="Copy your MCP endpoint URL">
    Go to **Settings → AI Connections → Settings** in your WordPress admin. Click the copy button next to the MCP endpoint URL.
  </Step>

  <Step title="Paste the URL into your AI client">
    Open your AI client (ChatGPT, Claude Desktop, Cursor, Codex, etc.) and paste the URL into the MCP connection field. The exact field name varies by client — look for "MCP server URL" or similar.
  </Step>

  <Step title="Let the client discover the auth server">
    The client sends a request to the endpoint, receives a `401` response pointing to your site's OAuth discovery URL, and automatically discovers the authorization endpoints. No manual configuration needed.
  </Step>

  <Step title="Authorize in the browser">
    Your browser opens a consent page. If you're not already logged in to WordPress, log in first. The consent page shows the client's name, the permissions it's requesting, and your current WordPress user identity. Click **Authorize**.
  </Step>

  <Step title="Done">
    The client receives its access token and connects to the MCP endpoint. Going forward, the client reconnects automatically — including silently refreshing tokens when they expire.
  </Step>
</Steps>

<Note>
  The consent page uses your WordPress login. The capability required to authorize defaults to `manage_options` (administrator). You can change this under **Settings → AI Connections → Settings**.
</Note>

## Token lifetimes

Maxi AI Core uses short-lived access tokens by design. A shorter access token window means a stolen token becomes useless quickly — and your AI client handles the refresh transparently.

| Token         | Notes                                                         |
| ------------- | ------------------------------------------------------------- |
| Access token  | Clients auto-refresh before expiry — no action needed         |
| Refresh token | Rotated on every use; a new refresh token is issued each time |

<Tip>
  You can override the default lifetimes using constants in `wp-config.php`. See [Configuration constants](/configuration/constants) for the full list.
</Tip>

## Managing connected clients

### Connected Clients tab

Go to **Settings → AI Connections → Connected Clients** to see every AI client that has registered with your site. For each client you can:

* View the client name and when it last made a request
* **Revoke all tokens** for that client, forcing it to re-authorize next time
* **Delete the client** entirely, removing its registration

### Active Sessions tab

The **Active Sessions** tab shows every non-expired, non-revoked token on your site, grouped by WordPress user. From here you can:

* Revoke individual tokens per session
* Click **Revoke all sessions for this user** to immediately invalidate all tokens for a given WordPress account — useful when an account is compromised

<Warning>
  Revoking a client or session disconnects the AI client immediately. The client will need to go through the browser consent flow again to reconnect.
</Warning>

## Settings

Go to **Settings → AI Connections → Settings** to configure OAuth behavior:

| Setting                          | Default          | Description                                                                                                              |
| -------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Auto-approve client registration | On               | AI clients register automatically when they first connect. Turn this off to require manual approval for each new client. |
| Required capability              | `manage_options` | The WordPress capability a user must have to see and approve the consent page.                                           |

## Disabling OAuth

If you need to fall back to application passwords entirely, add this line to `wp-config.php`:

```php theme={null}
define( 'MAXI_AI_OAUTH_DISABLE', true );
```

With this constant set, all OAuth endpoints return 404 and the Bearer token hook is not registered. Clients that use [application passwords](/connect/app-passwords) continue to work normally.

## Hosts that block `.well-known` paths

Some hosting environments (certain LiteSpeed and nginx configurations) block paths starting with a dot, which can interfere with standard OAuth discovery. Maxi AI Core handles this automatically — the `WWW-Authenticate` header points to a fallback discovery URL under `/wp-json/maxi-ai-oauth/v1/discovery/` that works everywhere. You don't need to do anything; OAuth discovery works on all supported hosts.