> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-agents/connect-your-platform/databricks.md).

# Databricks Genie Code

[Databricks](https://docs.databricks.com/aws/en/generative-ai/mcp) connects to CARTO as an **MCP service** – a Unity Catalog securable accessed through the Unity AI Gateway.

The Unity AI Gateway provides governance controls for MCP connections, including permissions, tool selection, rate limits, usage tracking, and auditing.

Today, the best way to leverage CARTO's MCP Server from within Databricks is by using [Genie Code](https://docs.databricks.com/aws/en/genie-code/). 

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FTXLQwYCMsuCTbgJhCTWy%2FScreenshot%202026-09-11%20at%2016.02.29.png?alt=media&amp;token=08d13bf9-5d84-4e14-a87a-b8422f08ddee" alt=""><figcaption></figcaption></figure>

## Requirements

Before you start, you need:

* A **Unity Catalog-enabled** Databricks workspace in a region that supports **Model Serving**.
* `CREATE CONNECTION` on the target schema. **Metastore admin access is not required.**
* Your CARTO **MCP Server URL**.
* Credentials for the CARTO MCP Server:
  * **OAuth (U2M):** recommended for access to the full CARTO tool surface.
  * **Bearer token:** sing a CARTO API Access Token for the [read-and-discovery subset](/carto-for-agents/mcp-server/connecting-with-api-tokens.md#what-a-token-unlocks).

## Install

The MCP server is registered through the Databricks UI or REST API. To do it from the UI, you should go to the AI Gateway section of the AI/ML module.&#x20;

### 1. Create a CARTO SPA OAuth Client

If you're using create a **SPA OAuth Client** in CARTO under **Developers > Credentials > SPA OAuth Clients**.

* Configure the client as **confidential** so that it has a **Client Secret**.
* Keep the **Client ID** and **Client Secret**. You'll enter these when configuring the Databricks MCP service.

Before creating the connection, add the Databricks workspace callback URL to the client's **Allowed Callback URLs**:

```
https://<workspace-host>/login/oauth/http.html
```

The callback is **workspace-specific**, so each Databricks workspace requires its own entry.

### 2. Create the MCP Service

In Databricks, go to:

**AI Gateway > MCPs**

Select:

**+ MCP > Connect an existing MCP server**

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FtsOe1PuFbG55kMzUjc3Q%2FScreenshot%202026-08-28%20at%2011.01.55.png?alt=media&amp;token=d69a13ac-dca5-44d7-9555-069e618b199b" alt=""><figcaption></figcaption></figure>

Configure the MCP service:

1. Select a **Catalog** and **Schema**.

   Use the actual catalog and schema where you want to register the MCP service. The form may prefill `main` and `default`, which may not exist in your workspace.
2. Enter a **Name**, for example:

   ```
   carto_mcp
   ```
3. Enter your CARTO **MCP Server URL**.
4. Select an **Authentication** method.

**OAuth (U2M)**

Use **OAuth (U2M)** for the full CARTO tool surface.

Enter:

* **Client ID:** your CARTO SPA OAuth Client ID.
* **Client Secret:** your CARTO SPA OAuth Client Secret.
* **Authorization endpoint:** `https://auth.carto.com/authorize`
* **Token endpoint:** `https://auth.carto.com/oauth/token`

Make sure the Databricks workspace callback URL has been added to the CARTO client's **Allowed Callback URLs** before connecting.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FrR0TdiuWZzZ0MNMnBJm2%2Fimage.png?alt=media&amp;token=2b95088d-3f5f-4bfd-b480-fb0ceee92c97" alt=""><figcaption></figcaption></figure>

**Bearer token**

Use **Bearer token** for the read-and-discovery path.

Enter your CARTO **API Access Token**. Databricks proxies the MCP calls, so the token is not exposed to end users.

The available capabilities depend on the APIs included in the token. The read-and-discovery subset includes browsing connections, running SQL, and searching the Data Observatory.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fxho6zIbkPQEIxyZv9Pme%2Fimage.png?alt=media&amp;token=4a5f24e5-249f-46d6-9f7d-fb5cfd4eb2fd" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Don't select **Dynamic Client Registration**. CARTO does not use DCR. Use **OAuth (U2M)** or **Bearer token**.
{% endhint %}

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2F4obEOmsvZNF9nDNsznNr%2FScreenshot%202026-08-28%20at%2011.17.55.png?alt=media&amp;token=14d4f29e-04ee-475c-bb73-70c2303811c5" alt=""><figcaption></figcaption></figure>

### 3. Load and configure the tools

Select **Create & load tools**.

Databricks discovers the tools exposed by the CARTO MCP server and displays them with **Read-only** or **Destructive** badges.

Under **Advanced**, you can filter the tools using globs, for example:

```
read_*list_*
```

Use the filter to expose only the CARTO tools required by your application.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FG3zPpjwe45tC1YpDdbZe%2FScreenshot%202026-08-28%20at%2011.17.08.png?alt=media&amp;token=13ebd868-af97-4028-9134-88156461f1c0" alt=""><figcaption></figcaption></figure>

### 4. Create the MCP Service

Create the service.

Once provisioning is complete, the MCP service status changes to **Active**.

{% hint style="info" %}
**Tool caps are surface-specific.** Databricks' **Genie Code** caps an agent at 20 tools across all servers – but with a per-tool picker, so you choose which of CARTO's tools to expose. The **AI Playground** has no such cap. Use the glob filter to keep a focused set and to exclude `view_map` (which can't render inline here).
{% endhint %}

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FyaWQfh9pUacXo2HcIGjJ%2FScreenshot%202026-08-28%20at%2011.18.49.png?alt=media&amp;token=9c7196f7-5cdd-4856-aa5b-a9b960052f6e" alt=""><figcaption></figcaption></figure>

## Governance

Databricks lets you go beyond a connection:

* **Tool selection:** expose only the tools you want (allowlist by prefix or exact match).
* **Service policies:** allow, deny, or require approval for individual tool calls. The Destructive badge is informational; set a policy to actually gate destructive tools.
* **Rate limits** and **usage tracking**: every call lands in `system.ai_gateway.usage`.

## Add the CARTO Agent Skills

[CARTO Agent Skills](https://docs.carto.com/carto-for-agents/agent-skills) are playbooks that teach the agent how to use the CARTO tools well: which tool to reach for, the right SQL dialect per warehouse, and recipes for common spatial analyses.

Today, only Databricks Genie Code supports the simultaneous use of both 3rd party MCP Server connections and Agent Skills.

In order to be able to leverage CARTO Agent Skills with Genie Code, you should first load them into your Databricks Workspace:

1. Go to your Workspace, and locate the folder `.assistant`&#x20;

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FAVFItYYdw8u3ewqBoViG%2FScreenshot%202026-09-11%20at%2015.46.48.png?alt=media&amp;token=ce498595-0bee-45ee-85e0-03c558519a05" alt=""><figcaption></figcaption></figure>

2. Create the folder Skills
3. Inside that folder, import CARTO Agent Skills. You can download the carto-skills-all.zip from [here](https://github.com/CartoDB/agent-skills/releases/download/v2026.09.07/carto-skills-all.zip).&#x20;

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FGlb6JD7d3AUmP8OhXzi8%2FScreenshot%202026-09-11%20at%2015.48.33.png?alt=media&amp;token=df209e44-5987-4712-8539-f5d83e8021de" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FjpvQeSoa7f0foksdF1oT%2FScreenshot%202026-09-11%20at%2015.50.57.png?alt=media&amp;token=d8e51cd4-190e-4b6d-810c-ca1b73e681d9" alt=""><figcaption></figcaption></figure>

## Customise Databricks Genie Code

We are now going to connect CARTO's MCP Server to Genie Code, and we'll also make available the Agent Skills that we have previously uploaded to our Databricks Workspace.&#x20;

1. Open Genie Code, and go to the "Customizations" section

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2F3kR2UzfmbxxnkrzkUyes%2FScreenshot%202026-09-11%20at%2015.52.43.png?alt=media&amp;token=3ed34bcb-2b8d-4dc6-8385-d01df9f09dcf" alt=""><figcaption></figcaption></figure>

2. In order to connect first the MCP Server, go into "Connectors" and click to "Add MCP server".&#x20;
3. In section **UC MCP Service** you should select the MCP Service that connects to CARTO MCP Server that has been previously created. Then click on the "Save" button.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FRw4IS8GnVEC4tIw0WkJc%2FScreenshot%202026-09-11%20at%2015.53.33.png?alt=media&amp;token=7bfecc7c-3272-4bcb-b6bb-336c391000ec" alt=""><figcaption></figcaption></figure>

&#x20;4\. Enable the UC MCP Service connector and click to "Configure tools".&#x20;

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2F9HQsSHqVtl4gPfXwzQcM%2FScreenshot%202026-09-11%20at%2015.55.12.png?alt=media&amp;token=d5ac3779-b9d7-4a57-9cfa-dd2136bac3aa" alt=""><figcaption></figcaption></figure>

5. Select which tools from CARTO's MCP Server are more relevant for your tasks. Note that you can always enable and disable tools based on what you are going to be asking Genie Code to do.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FCFulpFrALFUns8pWdWma%2FScreenshot%202026-09-11%20at%2015.56.13.png?alt=media&amp;token=44aa6410-4986-4187-a2c8-5b7e244792fa" alt=""><figcaption></figcaption></figure>

6. Now go to the section "Skills" on the Genie Code Customizations panel. There you should click to `"Add skill"`, and select the folder in your Workspace where you have added the CARTO Agent Skills previously.

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2Fr5Y8Y3j0AvJpE3Cprswg%2FScreenshot%202026-09-11%20at%2015.58.22.png?alt=media&amp;token=fa6c9260-f5eb-4266-aa9f-d8c5148abadf" alt=""><figcaption></figcaption></figure>

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2FlLob1cVU0gBoVUefe2bu%2FScreenshot%202026-09-11%20at%2015.58.52.png?alt=media&amp;token=7041a5b2-1c5a-47b2-97e0-225571ecb316" alt=""><figcaption></figcaption></figure>

7. Enable the Agent Skills that are relevant for your tasks, and there you go! You are ready to use Databricks Genie Code with CARTO's MCP Server and Agent Skills.&#x20;

<figure><img src="https://3029946802-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FybPdpmLltPkzGFvz7m8A%2Fuploads%2F8jOdAkjSvcCUurgH5KRh%2FScreenshot%202026-09-10%20at%2018.04.16.png?alt=media&amp;token=77414299-1b7c-40ac-8414-84c713ed96c5" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.carto.com/carto-for-agents/connect-your-platform/databricks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.