---
title: "Register an OAuth client for Grafana Cloud MCP | Grafana Cloud documentation"
description: "Learn how to register an OAuth client for an application that can't register with Grafana Cloud MCP automatically."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Register an OAuth client for Grafana Cloud MCP

Some applications that connect to Grafana Cloud MCP require you to provide a client ID and client secret because they don’t support Dynamic Client Registration (DCR) or Client ID Metadata Documents (CIMD). For these applications, register an OAuth client in Grafana and copy the generated configuration into the application.

The OAuth client identifies the application, not an individual user. Each user signs in to Grafana and authorizes their own connection using their existing Grafana permissions. Registering an OAuth client doesn’t grant access to Grafana data by itself. Users who connect through the application count as Grafana Assistant active users. Refer to [Billing and usage](/docs/grafana-cloud/ai-tools/mcp-servers/cloud-mcp/#billing-and-usage) for details.

If your application supports DCR or CIMD, follow [Connect your AI agent](/docs/grafana-cloud/ai-tools/mcp-servers/cloud-mcp/#connect-your-ai-agent) instead.

## Before you begin

To register and manage OAuth clients, you need the **Assistant Admin** role. Grafana organization administrators receive this role by default. Grafana Cloud MCP must also be enabled for your stack.

The application must support:

- The **Streamable HTTP** transport.
- The OAuth 2.1 authorization code flow with Proof Key for Code Exchange (PKCE) using the `S256` challenge method.
- Token endpoint authentication using `client_secret_basic` or `client_secret_post`.

You can register the OAuth client without a redirect URL and add one later.

## Register the OAuth client

Create the OAuth client and save its credentials:

1. In Grafana, navigate to **Assistant** > **Settings** > **Connectors** > **MCP clients**.
2. Under **OAuth clients**, click **Register client**.
3. Enter a **Client name** that identifies the application and environment.
4. In **Redirect URLs**, enter each redirect URL on a separate line. Leave this field empty if you don’t have a redirect URL yet.
5. Under **Allowed access**, choose the maximum access users can grant the application. Refer to [Choose allowed access](#choose-allowed-access) for details.
6. Click **Register client**.
7. Copy the **Client ID**, **Client secret**, and the values under **OAuth setup**. Grafana displays the client secret only once.

> Warning
> 
> Store the client secret securely. Don’t include it in source control, documentation, chat messages, or support requests. If you lose the secret, rotate it to generate a new one.

## Choose allowed access

The **Allowed access** setting limits the permissions users can grant the OAuth client. Choose one of these options:

Expand table

| Allowed access     | What users can grant                                                                                        |
|--------------------|-------------------------------------------------------------------------------------------------------------|
| **Read only**      | View dashboards, alerts, metrics, logs, and traces.                                                         |
| **Read and query** | Read access plus permission to run raw SQL queries. These queries execute as written and can modify data.   |
| **Full access**    | Read and query access plus permission to create and modify dashboards, alerts, incidents, and data sources. |

Each user can grant only permissions they already have in Grafana. To prevent raw SQL queries as well as write tools, choose **Read only**.

## Configure the application

Enter the values you copied from Grafana in the application’s OAuth configuration. The application might use different names for these fields.

Expand table

| Grafana value              | Common field names                                       |
|----------------------------|----------------------------------------------------------|
| **Client ID**              | Client ID, application ID                                |
| **Client secret**          | Client secret, application secret                        |
| **MCP server**             | MCP server URL, server URL, endpoint                     |
| **Authorization endpoint** | Authorization URL, authorization endpoint, authorize URL |
| **Token endpoint**         | Token URL, token endpoint                                |
| **Scopes**                 | Scopes, OAuth scopes                                     |

The **Scopes** field contains a generated value to copy into the application; it isn’t a control. The **Allowed access** setting determines the maximum scopes the OAuth client can request.

## Add a redirect URL

If you registered the OAuth client without a redirect URL, add it before users connect:

1. Navigate to **Assistant** > **Settings** > **Connectors** > **MCP clients**.
2. Open the action menu for the OAuth client and click **Edit client**.
3. In **Redirect URLs**, enter each redirect URL on a separate line.
4. Click **Save changes**.

Web redirect URLs must use HTTPS and must exactly match the URL sent during authorization. HTTP is supported only for loopback addresses, for example, `http://127.0.0.1:<PORT>/callback`. Native applications can use a private-use URI scheme. Wildcards aren’t supported.

## Manage the OAuth client

Use the action menu for an OAuth client to change or remove its registration:

- **Edit client**: Change the client name, redirect URLs, or **Allowed access** setting. Changes to **Allowed access** apply to new authorizations; existing connections keep their current access.
- **Rotate secret**: Generate a new client secret. The previous secret stops working immediately, but existing user connections remain active. Copy the new secret into the application.
- **Revoke client**: Disable the OAuth client and revoke every user connection associated with it. Existing access tokens stop working immediately.
- **Delete client**: Permanently remove the OAuth client and revoke every user connection associated with it. This action can’t be undone.

To revoke only your own connection, find it under **Your connections** and click **Revoke**. Other users’ connections remain active.

## Troubleshoot the connection

If authorization fails or expected tools aren’t available, check the relevant configuration:

- **`invalid_client`** : Confirm that the application uses the current client ID and secret and that the OAuth client hasn’t been revoked or deleted.
- **Redirect URL error**: Confirm that the URL in Grafana exactly matches the URL sent by the application, including its scheme, host, path, and query parameters. The port can vary for loopback redirect URLs.
- **PKCE error**: Confirm that the application uses PKCE with the `S256` challenge method. Grafana Cloud MCP doesn’t support authorization without PKCE.
- **Raw SQL query tools aren’t available**: Set **Allowed access** to **Read and query** or **Full access**, and confirm that the user grants **Query access** during authorization.
- **Write tools aren’t available**: Set **Allowed access** to **Full access**, and confirm that the user has permission to grant write access and selects **Write access** during authorization.

## Next steps

- [Configure read and write access](/docs/grafana-cloud/ai-tools/mcp-servers/cloud-mcp/#configure-read-and-write-access)
- [Manage Assistant access with RBAC](/docs/grafana-cloud/platform/grafana-assistant/privacy-and-security/rbac/)
- [Pricing and usage](/docs/grafana-cloud/platform/grafana-assistant/pricing/)