Looker-managed MCP server

The Looker-managed MCP server is a built-in integration that embeds a Model Context Protocol (MCP) server directly into the Looker platform. It allows AI agents — such as Gemini CLI, Claude Desktop, Cursor, and Copilot — to securely connect to a Looker instance and interact with business data and LookML models.

By hosting the server, Looker removes the need for you to deploy and maintain your own middleware infrastructure, providing a plug-and-play, secure, and governed gateway to trusted business insights.

If you're using a customer-hosted instance, or if you prefer to manage your own infrastructure, you can connect using the standalone MCP Toolbox for Databases. The MCP Toolbox is an open-source MCP server that you can run on your local computer or on your own server to act as a bridge between AI agents and your Looker instance. See the Use Looker with MCP, Gemini CLI and other agents documentation page for more information.

Before you begin

To use the Looker-managed MCP server, you must meet the following requirements:

Instance requirements

You must be using a Looker (Google Cloud core) or a Looker (original) instance.
The instance must be hosted by Looker.

Required permissions

To manage tool access: you must have the Admin Looker role.
To register or enable your AI agent as an OAuth client: you must have the Admin Looker role.
To connect an AI agent to the Looker-managed MCP server: you need your standard Looker login credentials to authenticate during the OAuth connection process. The AI agent must first be registered as an OAuth client by a Looker admin. Once connected, the AI agent will inherit the Looker roles and access of the user who authenticated.

Set up the managed MCP server

Configure tool access to set up the managed MCP server.

Configure tool settings

By default, all tools are disabled for the managed MCP server. Looker admins must explicitly enable the tools that AI agents are allowed to use. See the Admin settings - Model Context Protocol (MCP) documentation page for steps to enable tools.

Configure CORS settings

If the MCP client is running directly in a web browser and wants to communicate with the Looker-managed MCP server using CORS, the Looker admin must add the domain of that client website to the Embedded Domain Allowlist in the Admin panel.

Register an AI agent through OAuth

To connect an AI agent to the Looker-managed MCP server, an administrator must enable or register the AI agent as an OAuth client application on the Manage OAuth Clients page in the Looker Admin panel.

You can enable pre-configured AI clients from the Application Library or register a custom client on the Custom Clients tab:

Application Library (recommended): Use pre-configured, Looker-managed OAuth client registrations for popular AI agents and developer tools such as Cursor, VS Code, Claude Code, Claude Desktop, ChatGPT, Gemini CLI, Cline, Windsurf, Antigravity, and the Looker Extension for VS Code.
Custom Clients: Register a new custom OAuth client if your AI tool is not available in the Application Library or if you need to configure a custom redirect URI or port.

Option 1: Enable a pre-configured AI agent from the Application Library

We recommend checking the Application Library tab first.

To enable a pre-configured AI agent client, follow these steps:

In the Looker Admin panel, navigate to the Authentication section and select Manage OAuth clients.
Select the Application Library tab.
Locate the client application for your AI agent (for example, Cursor, Claude Code, Cline, or Gemini CLI). You can use the search bar to filter by name.
Turn the Enable switch to ON.
Copy the Client ID that's displayed on the client's row. You will provide this client ID when you configure your AI agent's MCP settings (for example, in mcp.json or startup flags). If Looker users who don't have the Looker Admin role need to use this client, distribute the Client ID to them.

Redirect URIs and dynamic port handling

Looker requires OAuth redirect URIs to match registered values exactly and doesn't support wildcard redirect URIs. Some AI tools use dynamic or ephemeral local ports by default when initiating an OAuth callback (such as Claude Code or Cline). To accommodate these tools, Looker pre-registers a fixed default port for each library client (for example, port 8080 for Claude Code and Cline, or port 7777 for Gemini CLI).

To use a pre-configured library client with dynamic ports, choose one of the following options:

Configure your client to use the pre-registered static port: In your tool's settings or startup command, specify the pre-registered port. For example:
- Claude Code: Run Claude Code with the --callback-port 8080 flag (or configure "callbackPort": 8080 in mcp.json).
- Cline: Configure the OAuth callback port to 8080.
- Gemini CLI: Set the environment variable export OAUTH_CALLBACK_PORT=7777.
- VS Code: Use the pre-registered static URI http://127.0.0.1:33418/.
Register a custom client: If you need to use a different port or custom callback URL, register a custom client with your preferred redirect URI as described in the next section.

Option 2: Register a custom AI agent client

If your AI agent isn't included in the Application Library, or if you need to use a custom callback URL or port, complete the steps in the Admin settings - Manage OAuth Clients documentation to register a custom client. After you have added the client, copy the Client ID for use when configuring the MCP client.

Programmatic registration (API Explorer or API)

For automated deployments (such as CI/CD pipelines or provisioning scripts), Looker admins can register OAuth clients programmatically.

Expand this section to see how to register an OAuth client by using the API or API Explorer.

You can register an AI agent by using the oauth_client_apps API endpoint directly with curl:

curl -X POST "https://LOOKER_INSTANCE_URL/api/4.0/oauth_client_apps/CLIENT_GUID" \
-H "Authorization: token ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "redirect_uri": "REDIRECT_URI",
  "display_name": "CLIENT_NAME",
  "description": "OAuth client to access MCP server using CLIENT_NAME",
  "enabled": true
}'

Alternatively, you can use the Looker API Explorer:

Under the Auth method, find the Register OAuth App API endpoint.
Click Run It, enter the CLIENT_GUID, redirect_uri, display_name, and description, select the confirmation checkbox, and then click Run.
- Gemini CLI
```
http://localhost:7777/oauth/callback
```
  Note: Some tools, such as Gemini CLI, may require you to set an environment variable (for example, export OAUTH_CALLBACK_PORT=7777) to ensure that the tools use a static port that matches your registered redirect URI.
- Gemini Code Assist
```
http://localhost:7777/oauth/callback
```
  We recommend using Gemini CLI with Gemini Code Assist, in which case they will share the same local callback server and port configuration.
- Gemini Enterprise
```
https://vertexaisearch.cloud.google.com/oauth-redirect
```
- Claude code
  Claude Code uses a random available port for OAuth callback, but you should fix it by using the --callback-port 8080 flag (or with the callbackPort setting in mcp.json) to match your registered URI.
```
http://localhost:8080/callback
```
- VS Code
  For VS Code, use the following URI.
```
http://127.0.0.1:33418/
```
  Note: The trailing slash (/) at the end of the URI is required.
- Cloud-hosted apps
  For Cloud-hosted applications, it may look like a secure HTTPS URL:
```
https://AI_AGENT_URL/oauth2callback
```
- Local apps
  For applications running locally, the redirect URI should be a localhost URL with a static port:
```
http://localhost:7777/oauth/callback
```
  Note: Some tools, such as the Gemini CLI, may require you to set an environment variable (for example, export OAUTH_CALLBACK_PORT=7777) to ensure that the tools use a static port that matches your registered redirect URI.
To verify registration, run the Get OAuth Client App endpoint with your CLIENT_GUID.

Configure the MCP client

Once the AI agent is registered, you can connect it to the managed MCP endpoint as an MCP client. Refer to your agent's documentation to complete client setup.

Server URL: LOOKER_INSTANCE_URL/mcp
Authentication: OAuth 2.1

Example configurations (mcp.json)

This section describes how to configure various developer tools to connect to your Looker instance using the Looker-managed MCP server. The MCP server sits between your IDE and Looker, providing a secure and efficient control plane for your AI tools. Select the tab for your specific tool to see the configuration instructions.

Gemini CLI

Configure the Gemini CLI to connect directly to the Looker-managed MCP server.

Install the Gemini CLI.
Add the remote MCP server using the following command, replacing LOOKER_INSTANCE_URL with the your Looker instance URL:
```
gemini mcp add --transport http looker LOOKER_INSTANCE_URL/mcp
```
Alternatively, you can configure this manually by adding the following configuration to your settings.json file (located in ~/.gemini/settings.json or your project directory):
```
{
  "mcpServers": {
    "looker": {
      "httpUrl": "LOOKER_INSTANCE_URL/mcp",
      "oauth": {
        "clientId": "CLIENT_GUID"
      }
    }
  }
}
```
Start the Gemini CLI in interactive mode:
```
gemini
```
When prompted to connect, the CLI initiates the OAuth authorization flow to securely authenticate with your Looker instance.

Gemini Code Assist

We recommend that you configure Gemini Code Assist to use the Gemini CLI. This approach removes the need to manually configure an MCP server.

Make sure that you have installed and configured the Gemini CLI and the Looker-managed MCP server.
Configure Gemini Code Assist to use the Gemini CLI.
Start interacting with your Looker instance by using natural language directly within the Gemini Code Assist chat.

Gemini Enterprise

Configure Gemini Enterprise to connect to the Looker-managed MCP server as a custom MCP server datastore.

Follow the official documentation to create a custom MCP server datastore in Gemini Enterprise.
For the datastore configuration, use the following values, replacing LOOKER_INSTANCE_URL with your Looker instance URL and CLIENT_GUID with the exact string that you used during your OAuth app registration:
```
{
  "instance_uri": "LOOKER_INSTANCE_URL/mcp",
  "auth_uri": "LOOKER_INSTANCE_URL/auth",
  "auth_uri_params": "&response_type=code&code_challenge_method=S256",
  "token_uri": "LOOKER_INSTANCE_URL/api/token",
  "client_id": "CLIENT_GUID",
  "client_secret": "none",
  "scopes": "cors_api",
  "pkce_support_enabled": "true"
}
```
PKCE does not require an OAuth client secret, but Gemini Enterprise requires a value in the client_secret field. You can enter none as shown in the example configuration.
Authenticate through OAuth to proceed.

Set the MCP server description to help Gemini understand when to invoke the server. For example:

Looker Agent with API access to various aspects of Looker. Primarily used to fetch data and run dashboards from Looker.

Define the MCP server agent instructions. For example:

Use this server exclusively to interact with the Looker instance for monitoring health, checking status, and retrieving data.
Invoke the Looker MCP server for the following request categories:
  - Instance Health Checks: Auditing connection status, uptime, performance metrics, or system errors.
  - Analytics Queries & Data Retrieval: Fetching live business metrics from Explores, Looks, or Dashboards.
Strict Constraints:
  - No Local Estimation: Do not guess. Always fetch real-time data via MCP tools.
  - Fallback Behavior: Inform the user of connectivity failures immediately.

Navigate to the Actions tab in the custom MCP datastore that you just created and enable the tools that you want Gemini Enterprise to use.
Note: While you must also enable tools in the Looker Admin settings, this step is required for Gemini Enterprise to discover and use the MCP tools.
Finalize the setup by navigating to Gemini Enterprise, clicking the Connector icon, and authorizing the MCP server.

Claude code

Install Claude Code.
Create the .mcp.json file in your project root, if it doesn't exist.
Add the following configuration, replacing LOOKER_INSTANCE_URL with the URL of your Looker instance and CLIENT_GUID with your OAuth client GUID, and then save.

      {
        "mcpServers": {
          "looker": {
            "type": "http",
            "url": "LOOKER_INSTANCE_URL/mcp",
            "oauth": {
              "clientId": "CLIENT_GUID",
              "callbackPort": 8080
            }
          }
        }
      }

Claude desktop

In Claude desktop, navigate to Settings and select Connectors.
Choose Add custom connector and enter a name (for example, Looker).
For the URL, enter the URL for your Looker instance with the /mcp path appended (for example, https://looker.example.com/mcp).
Under Advanced settings, enter the exact string that you used for the CLIENT_GUID during your OAuth app registration. Leave the OAuth client secret blank.
Select Add to save the connector. When prompted to connect, Claude desktop securely initiates the PKCE authorization flow through your browser.

Restart Claude desktop.

Cline

Open the Cline extension in your IDE and click the MCP Servers icon.
Click Configure MCP Servers to open the configuration file.
Add the following configuration, replacing LOOKER_INSTANCE_URL with your Looker URL, and then save.

      {
        "mcpServers": {
          "looker": {
            "type": "http",
            "url": "LOOKER_INSTANCE_URL/mcp"
          }
        }
      }

A green active status appears after the server connects successfully.

Cursor

Create the .cursor directory in your project root if it doesn't exist.
Create the .cursor/mcp.json file if it doesn't exist, and open it.
Add the following configuration, replacing LOOKER_INSTANCE_URL with your Looker URL, and then save.

      {
        "mcpServers": {
          "looker": {
            "url": "LOOKER_INSTANCE_URL/mcp",
            auth: {
              "CLIENT_ID": "CLIENT_GUID"
            }
          }
        }
      }

Open Cursor and navigate to Settings > Cursor Settings > MCP. A green active status appears when the server connects.

Visual Studio Code (Copilot)

Open VS Code and create the .vscode directory in your project root if it doesn't exist.
Create the .vscode/mcp.json file if it doesn't exist, and open it.
Add the following configuration, replacing LOOKER_INSTANCE_URL with the URL of your Looker instance, and then save.

      {
        "servers": {
          "looker": {
            "type": "http",
            "url": "LOOKER_INSTANCE_URL/mcp"
          }
        }
      }

Windsurf

Open Windsurf and navigate to Cascade assistant.
Click the MCP icon, then click Configure to open the configuration file.
Add the following configuration, replacing LOOKER_INSTANCE_URL with the URL of your Looker instance, and then save.

      {
        "mcpServers": {
          "looker": {
            "type": "http",
            "url": "LOOKER_INSTANCE_URL/mcp"
          }
        }
      }

Authenticate with the client

After you have configured your MCP client with the mcp.json settings, the first time you attempt to interact with Looker through that client, it will initiate the OAuth 2.1 authentication flow. This typically involves the client opening a browser window where you must log in to your Looker instance using your standard credentials and grant the application permission to access Looker on your behalf.

This login process is the interactive authentication step that allows the MCP client to obtain an access token for making future requests.

See your client's documentation for further details.

Once connected, the client will inherit your Looker roles and content access. The client will also have access to the AI tools that your Looker admin has enabled for the MCP server. For a list of all possible tools, see the Use AI tools documentation.

Security and governance

The managed MCP server is designed to inherit Looker's existing security and governance framework.

Permissions boundary: The server enforces strict user-level permissions. An AI agent cannot access data or models that the authenticated user is not authorized to see.
VPC Service Controls: For Looker (Google Cloud core) instances that use VPC Service Controls, the managed MCP endpoint respects existing VPC Service Controls boundaries with no additional policies or configurations required.
Customer-managed encryption keys (CMEK): For Looker (Google Cloud core) instances that use CMEK, the managed MCP server is CMEK-compliant with no additional policies or configurations required.
IP allowlists: For instances that use an IP allowlist in Looker (Google Cloud core) or Looker (original), the managed MCP endpoint respects existing IP allowlist rules without requiring any additional configurations.

Audit logging

Every action taken by an AI agent is logged in Looker System Activity and Cloud Audit Logs.

System Activity

Looker-managed MCP server activity is tracked in the History and Event Attribute Explores. The Monitoring Looker usage with System Activity Explores documentation page provides the following sample queries:

Cloud Audit Logs

Looker (Google Cloud core) instances also track Looker-managed MCP server activity through Cloud Audit Logs. The Looker (Google Cloud core) audit logging documentation page provides sample queries.

Limitations

Fine-grained scopes: OAuth scopes are not yet supported for the managed MCP server. Access control relies on the global tool allowlist and the user's base permissions.
Dynamic registration: Dynamic Client Registration is not supported in the preview.
Client refresh: Changes to the tool allowlist are not automatically pushed to connected clients. Users must wait 30 seconds after making a change to the tool list and then reconnect their client to refresh the tool manifest. See your client's documentation for information about how to reconnect to the MCP server.
Server capacity: During the preview phase, the managed MCP server is configured with a fixed capacity to help us gather performance data. During periods of peak usage, you may experience occasional timeouts. This is expected behavior.

Pricing and quotas

The Looker-managed MCP server is available at no additional cost. However, tool calls made by AI agents consume the instance's standard administrative and query-based API quotas. High agent activity may impact your available API quota.