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

# MCP OAuth

> Connect Claude, ChatGPT and other OAuth-capable MCP clients without pasting a key.

MCP clients that support OAuth can connect to the ManaLens MCP server without a key. You sign in, choose **one project** and the scopes, and the client gets short-lived access to that project. [API keys](https://docs.manalens.dev/mcp/overview.md) keep working.

OAuth is available when your API operator has enabled it. If the client says that the server does not support OAuth, use an [API key](https://docs.manalens.dev/mcp/overview.md#create-an-api-key).

## Who can connect

* You must be an **owner** or **admin** of the project's workspace.
* You need a verified MFA session ([MFA](https://docs.manalens.dev/security/mfa.md)) to approve, the same rule as creating an API key. Without an authenticator, the consent page sends you to Account security to set one up.
* The workspace needs an active subscription or trial.

## Connect a client

The MCP server URL is `https://YOUR_COLLECTOR_ENDPOINT/mcp`.

> [tab] Claude
>
> 1. In Claude, open **Settings**, then **Connectors**.
> 2. Click **Add custom connector**.
> 3. Enter a name, for example `ManaLens`, and the MCP server URL.
> 4. Click **Add**, then **Connect**.
> 5. Sign in to ManaLens. On the consent page, choose the project and the scopes, then click **Allow access**.

> [tab] ChatGPT
>
> 1. In ChatGPT, open **Settings**, then **Apps**, then **Advanced settings**, and turn on **Developer mode**.
> 2. Go back to **Apps** and click **Create app**.
> 3. Enter a name, the MCP server URL, and choose **OAuth** for authentication.
> 4. Click **Create**.
> 5. Sign in to ManaLens, choose the project and the scopes, then click **Allow access**.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http untitled-analytics https://YOUR_COLLECTOR_ENDPOINT/mcp
> ```
>
> Then run `/mcp` in Claude Code and choose **Authenticate**. Your browser opens the consent page.

> [tab] Others
>
> Add a remote MCP server with the URL above and choose OAuth if the client asks. The client must support PKCE with S256 and redirect to an `https` address or to a loopback `http` address (`localhost`, `127.0.0.1` or `[::1]`). Clients that redirect to a custom scheme, such as `cursor://`, cannot use OAuth yet; use an [API key](https://docs.manalens.dev/mcp/overview.md#create-an-api-key) instead.

## The consent page

The consent page shows:

* **The app name.** The app chooses this name itself, so it is not verified.
* **The return address.** After you approve, your browser goes to this host. Continue only if you started the connection and you trust this address.
* **The project.** Choose one. The app can read only this project.
* **The scopes.** Clear a scope to give less access. You cannot give a scope that the app did not ask for.

Click **Deny** to send the app away with no access.

## Scopes

| Scope | Tools |
| - | - |
| `analytics:read` | `get_analytics`, `describe_schema` |
| `dashboards:read` | `list_dashboards`, `get_dashboard`, `list_charts`, `get_chart` |
| `attribution:read` | `get_attribution` |
| `profiles:read` | `get_profile` |
| `query:read` | `execute_query`, `preview_chart` |
| `dashboards:write` | `create_dashboard`, `update_dashboard`, `delete_dashboard`, `create_chart`, `update_chart`, `delete_chart`, `duplicate_chart`, `move_chart`, `reorder_charts` |

The consent page checks the read scopes only. Check **SQL** (`query:read`) or **Dashboard changes** (`dashboards:write`) to give the app that access. Each scope is explicit: `dashboards:write` does not include `dashboards:read`, so an app that changes dashboards and also lists them needs both. Changes the app makes are audited as you. These are the same scopes as for [API keys](https://docs.manalens.dev/mcp/overview.md#scopes). The server shows and runs only the tools that the granted scopes allow. A client can also ask for `offline_access`; the server accepts it and ignores it.

## Tokens and lifetimes

| Item | Lifetime |
| - | - |
| Access token | 1 hour |
| Refresh token | 30 days, and a new one replaces it at each use |
| Authorization code | 60 seconds, one use |
| Consent request | 10 minutes |

The client refreshes access in the background. A connection that is not used for 30 days ends.

## See and revoke connected apps

Open your project, go to **Settings**, then **Integrations**. **Connected MCP apps** lists each app, its return host, scopes, the person who connected it, and when it was last used. Owners and admins with a verified MFA session can click **Revoke**. The app stops at its next request.

Access also stops when:

* the person who connected the app leaves the workspace or becomes an editor or viewer;
* the app revokes its own token;
* a refresh token is used a second time (this means that it was copied, so the whole connection is revoked).

## Limits

Each connected app has the same budget as a key: 120 requests per minute. The workspace budget of 600 requests per minute is shared by keys and apps. An exhausted budget returns `429` with `Retry-After: 60`.

## Troubleshooting

* **The client does not start OAuth.** Check the URL ends in `/mcp`. Ask your operator whether OAuth is enabled.
* **"Request unavailable".** The consent request expired after 10 minutes or was already used. Start again from the client.
* **No project can be chosen.** You must be an owner or admin, and the workspace needs an active subscription.
* **The redirect URI is not registered.** The client sent a different return address from the one it registered. Remove the server from the client and add it again.

## OAuth endpoints

Clients find these automatically. An unauthenticated request to `/mcp` returns `401` with a `WWW-Authenticate` header that points to the protected resource metadata.

| Metadata | URL |
| - | - |
| Protected resource (RFC 9728) | `https://YOUR_COLLECTOR_ENDPOINT/.well-known/oauth-protected-resource/mcp` |
| Authorization server (RFC 8414) | `https://YOUR_COLLECTOR_ENDPOINT/.well-known/oauth-authorization-server` |
| Registration (RFC 7591) | `https://YOUR_COLLECTOR_ENDPOINT/oauth/register` |
| Authorization | `https://YOUR_COLLECTOR_ENDPOINT/oauth/authorize` |
| Token | `https://YOUR_COLLECTOR_ENDPOINT/oauth/token` |
| Revocation (RFC 7009) | `https://YOUR_COLLECTOR_ENDPOINT/oauth/revoke` |

## Security

* Authorization code flow with PKCE. Only `S256` is accepted.
* Redirect URIs must match the registered value exactly.
* Every access token is bound to one project, one connection and the `/mcp` URL.
* Refresh tokens, codes and client secrets are stored only as SHA-256 hashes. Access tokens are not stored.
* Connecting and revoking an app are written to the workspace audit log.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.