Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow AI toolsbreadcrumb arrow MCP serversbreadcrumb arrow Register an OAuth client
Grafana Cloud

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 for details.

If your application supports DCR or CIMD, follow 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 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:

Allowed accessWhat users can grant
Read onlyView dashboards, alerts, metrics, logs, and traces.
Read and queryRead access plus permission to run raw SQL queries. These queries execute as written and can modify data.
Full accessRead 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.

Grafana valueCommon field names
Client IDClient ID, application ID
Client secretClient secret, application secret
MCP serverMCP server URL, server URL, endpoint
Authorization endpointAuthorization URL, authorization endpoint, authorize URL
Token endpointToken URL, token endpoint
ScopesScopes, 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