> For the complete documentation index, see [llms.txt](https://docs.p0.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.p0.dev/agentic-access/agentic-gateway/mcp-server/databricks.md).

# Databricks MCP servers

Install the Databricks (AI) integration and its MCP servers so agents behind the P0 AI Gateway can request temporary access to Unity Catalog data in your Databricks accounts.

The **Databricks (AI)** integration lets agents behind the [P0 Runtime Access for AI](https://docs.p0.dev/readme/agentic-control-plane.md) request temporary access to data in your Databricks accounts: one catalog, schema, table, view, or volume in one workspace, queried on one SQL warehouse. For each approved request, P0 creates a Databricks service principal named `p0-agent-<request ID>` and grants it only what the request asks for. The gateway calls Databricks' Genie and Databricks SQL MCP servers as that principal. When the grant ends, P0 hands everything the agent created to an owner principal you choose, then deletes the agent's principal.

Only agents can use this integration. People request Databricks access through the [Databricks](https://docs.p0.dev/integrations/resource-integrations/databricks.md) integration, which is separate.

{% hint style="info" %}
The Databricks (AI) integration is in beta. Functionality and configuration may change.
{% endhint %}

Setup has four parts, in this order:

1. Install the connector, a Lambda function in your AWS account.
2. Install each Databricks account, which creates P0's service principal there.
3. Add the Databricks MCP servers to your gateway, one of each for every workspace agents use.
4. Write the policies that decide which agents get which access.

## Prerequisites

* A registered [Gateway](https://docs.p0.dev/agentic-access/agentic-gateway/gateway.md) component, with the gateway deployed in your environment. The gateway must be able to reach your Databricks workspaces over HTTPS.
* A Databricks account on AWS, with at least one running workspace. Databricks accounts on Azure and Google Cloud aren't supported.
* An AWS account for the connector, with P0's AWS **IAM management** installed for it. See [Setting up AWS IAM management](https://docs.p0.dev/integrations/resource-integrations/aws/installation-methods.md). P0 invokes the connector through that integration's role. The connector must run in a commercial AWS region, not in GovCloud or China.
* An AWS admin of that account, to deploy the connector. Its Terraform turns on outbound web identity federation for the whole AWS account. See [Installing Databricks](https://docs.p0.dev/integrations/resource-integrations/databricks/installation.md#outbound-web-identity-federation) on the Databricks page, which applies to this connector too.
* A Databricks account admin, to apply the account's Terraform. P0 has you add it to the configuration that holds the connector, so whoever applies it also needs AWS access to the connector's account.
* An admin group on every metastore in the account. The account's Terraform adds P0's service principal to each one, which makes it metastore admin. A metastore that P0's service principal owns directly also passes. A metastore whose admin is a user, or that has no admin, fails P0's install check.
* An owner principal, to own what agents create once their access ends: a group, a user, or a service principal in the account.
* Terraform 1.4 or later, with version 6.36.0 or later of the `hashicorp/aws` provider, version 1.115.0 or later of the `databricks/databricks` provider, and version 3.x of the `kreuzwerker/docker` provider. P0's RDS security perimeter and Postgres or MySQL connector modules pin the AWS provider to 5.x, so keep the connector's Terraform in a configuration without them.
* `docker` and the AWS CLI wherever you run the connector's Terraform, with the AWS CLI signed in to the connector's AWS account. The Terraform copies P0's connector image into Amazon ECR with them.
* Databricks workspaces and an account console that are reachable over the public internet. Workspaces that accept only private connections, and workspaces or account consoles that limit access with an IP access list, aren't supported.
* For the SQL tools, the Unity Gateway beta turned on in the account. See [#turn-on-the-sql-tools](#turn-on-the-sql-tools "mention").

## What P0 holds

P0 manages each Databricks account through one service principal of its own, `p0-databricks-ai`, which the account's Terraform creates. It holds these roles:

| Role            | Why P0 needs it                                                                                                                              | Where                                                                                                                                                          |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Account admin   | To create and delete each grant's service principal and its federation policy, assign it to the workspace, and find the account's workspaces | The account                                                                                                                                                    |
| Metastore admin | To grant Unity Catalog privileges on any catalog, and to hand what an agent created to the owner principal when its access ends.             | Every metastore in the account, as a member of its admin group                                                                                                 |
| Workspace admin | To let each agent's principal use the SQL warehouse its request names                                                                        | Each workspace an agent lists or requests, and the account's lowest-ID running workspace when you save the account, where P0 checks for the Unity Gateway beta |

P0 never removes its own workspace admin assignments.

P0 never:

* Gives an agent's principal an admin role, `MANAGE`, `ALL_PRIVILEGES`, or `CREATE_SCHEMA`.
* Stores a Databricks secret. The connector signs in to Databricks with short-lived identity tokens that AWS issues to its role, and Databricks accepts them only for P0's service principal, whose federation policy trusts that role.

When P0 assigns an agent's principal to its workspace, Databricks adds the principal to that workspace's `users` group, so it also inherits the group's default entitlements.

{% hint style="warning" %}
Anyone who can invoke the connector, change it, or use its role can act as P0's service principal: account admin, and metastore admin on every metastore. To limit who can, deploy the connector in a dedicated AWS account, and restrict `lambda:InvokeFunction` on it, for example with a service control policy.
{% endhint %}

## Install the connector

1. Navigate to **Integrations** on [p0.app](https://p0.app), select **Databricks (AI)**, and choose the **Connector** component.
2. Add a connector, choose the AWS account it runs in, and choose its region. P0 lists only AWS accounts where its AWS IAM management is installed.
3. P0 generates a Terraform configuration in two parts: the providers it needs, and the connector itself. Copy both into your Terraform project, apply them as an AWS admin of the account, then click **Next**.

   The configuration creates, in the connector's AWS account and region:

   * A Lambda function, `p0-connector-databricks-ai`, and its IAM role, which can request AWS identity tokens only for the audience `databricks`.
   * An ECR repository, `p0-connector-databricks-ai`, with immutable tags and scan on push, and a copy of P0's connector image in it.
   * A CloudWatch log group, `/aws/lambda/p0-connector-databricks-ai`, with 30-day retention.
   * Permission for P0's AWS IAM management role to invoke the connector.
   * Outbound web identity federation for the AWS account. If it's already on, import it as the comments in the Terraform say.
4. P0 checks that it can invoke the connector. A new Lambda can take a few seconds to deploy. If the check fails, wait a minute and click **Next** again.
5. Review the summary and click **Finish**.

One connector can reach several Databricks accounts.

## Install a Databricks account

1. On the **Databricks (AI)** integration, choose the **Account** component and add an account. Enter its Databricks account ID, a UUID. To find it, see Databricks' [Locate your account ID](https://docs.databricks.com/aws/en/admin/account-settings/#locate-your-account-id).
2. Choose the connector that reaches the account, and enter the account's console URL, `https://accounts.cloud.databricks.com`. Click **Next**.
3. P0 generates the account's Terraform. Add it to the configuration that holds the connector. It creates:
   * P0's service principal, `p0-databricks-ai`, with the account admin role.
   * A federation policy that lets the connector's role sign in as that principal.
   * A membership of each metastore admin group you list.
   * An output that holds the principal's application ID.
4. Set the Terraform variable whose name ends in `_metastore_admin_groups` to the display name of each metastore's admin group. Apply the configuration as a Databricks account admin with AWS access to the connector's account, then click **Next**.
5. Fill in the account details, then click **Next**:
   * **Service principal application ID**: the value that the `terraform output -raw` command P0 shows prints.
   * **Owner principal**: who owns what an agent created once its access ends. Enter a group's display name, a user's userName, or a service principal's application ID.
6. P0 checks the account, in this order, and stops at the first check that fails, with a message that says what to change:

   * P0 can sign in to Databricks as its service principal.
   * The principal is an account admin.
   * The principal is metastore admin of every metastore in the account.
   * The owner principal names exactly one group, user, or service principal.

   Then P0 checks whether the Unity Gateway beta is on. It makes itself workspace admin of the running workspace with the lowest ID, and asks that workspace's Databricks SQL MCP server. If the beta is off, the install still finishes, and the account shows a warning. See [#turn-on-the-sql-tools](#turn-on-the-sql-tools "mention"). If the account has no running workspace, the install fails. Create a workspace, or wait for one to be running, then open the account in P0 and click **Update**.

   On the first save, P0 can fail with a message that Databricks hasn't seen its new workspace admin assignment yet. Wait a few minutes, then save the account again, or apply again. If the beta warning then shows although the beta is on, save the account again.
7. Review the summary and click **Finish**. The account now appears with the state **Installed**.

P0 repeats the four checks every hour, so it notices if its service principal loses a role.

### Install with Terraform

Instead of the installer, you can install the connector and each account with the P0 Terraform provider (see [Manage integrations as code with the P0 Terraform provider](https://docs.p0.dev/getting-started/get-started-with-the-p0-terraform-provider.md)). Create the resources in this order:

1. **Stage the connector** with [`p0_databricks_ai_connector_staged`](https://registry.terraform.io/providers/p0-security/p0/latest/docs/resources/databricks_ai_connector_staged). Set `id` to the AWS account the connector runs in, and `region` to its region.
2. **Deploy the connector** in that account and region, and let P0's AWS IAM management role invoke it.
3. **Install the connector** with [`p0_databricks_ai_connector`](https://registry.terraform.io/providers/p0-security/p0/latest/docs/resources/databricks_ai_connector), with the same `id` and `region`. P0 checks that it can invoke the connector.
4. **Stage each account** with [`p0_databricks_ai_account_staged`](https://registry.terraform.io/providers/p0-security/p0/latest/docs/resources/databricks_ai_account_staged). Set `id` to the Databricks account ID, `connector` to the connector's `id`, and `accounts_url` to the account's console URL.
5. **Create P0's service principal** in the account, with its federation policy, the account admin role, and a membership of each metastore admin group.
6. **Install the account** with [`p0_databricks_ai_account`](https://registry.terraform.io/providers/p0-security/p0/latest/docs/resources/databricks_ai_account). Set the staged account's `id`, `connector`, and `accounts_url`, the principal's `application_id`, and an `owner_principal`. P0 runs the checks in [#install-a-databricks-account](#install-a-databricks-account "mention").

Step 1 alone is this one resource, from the provider's `p0_databricks_ai_connector_staged` example:

```terraform
resource "p0_databricks_ai_connector_staged" "example" {
  id     = "123456789012"
  region = "us-east-1"
}
```

The provider's example for `p0_databricks_ai_connector` does steps 1 to 3 in one configuration. Set `account_id` and `region` in its `locals`:

```terraform
# Installs the Databricks (AI) connector: one Lambda per AWS account, outside
# any VPC, that P0 invokes to give AI agents access to your Databricks
# accounts. It holds no secret: it exchanges an AWS identity token for each
# account's service principal. Apply it as an AWS admin of the connector's
# account.
#
# Before you apply this, install P0's AWS IAM management for the connector's
# AWS account (see p0_aws_iam_write). P0 invokes the connector as that
# installation's role. Once the connector is installed, add Databricks
# accounts (see p0_databricks_ai_account).

terraform {
  # 1.4 added terraform_data.
  required_version = ">= 1.4"

  required_providers {
    # 6.26.0 added outbound identity federation. This asks for 6.36.0, which
    # added its data source, to match the p0_databricks_ai_account example.
    aws = {
      source  = "hashicorp/aws"
      version = ">= 6.36.0"
    }
    docker = {
      source  = "kreuzwerker/docker"
      version = "~> 3.0"
    }
    # 0.82.0 added the p0_databricks_ai resources.
    p0 = {
      source  = "p0-security/p0"
      version = ">= 0.82.0"
    }
  }
}

locals {
  account_id = "123456789012"
  region     = "us-east-1"

  # The connector's name. P0 invokes it by this name, in the account and region
  # above, so keep it as it is. The connector's Lambda function, role, log group
  # and ECR repository all take it.
  connector_name = "p0-connector-databricks-ai"

  # How many days CloudWatch keeps the connector's logs.
  log_retention_days = 30

  # The role that P0's AWS IAM management assumes in this account, which
  # invokes the connector.
  p0_role_name = "P0RoleIamManager"

  # The connector image's version: the sha- tag P0 publishes each release
  # under, and the digest that tag must resolve to. Docker Hub lets a tag be
  # pushed again, so the plan fails if the tag no longer resolves to this
  # digest. To update, take both from the latest version of this example in
  # the Terraform registry: they change together. Changing them copies the
  # image again and redeploys the Lambda.
  connector_image_name   = "p0security/p0-connector-databricks-ai"
  connector_image_tag    = "sha-551bc5e"
  connector_image_digest = "sha256:cb07df600ac74e25c939a36b3b0eef57afc674e6d339cf5a216e4c411f57a09b"

  tags = {
    ManagedBy  = "Terraform"
    ManagedFor = "P0"
  }
}

provider "aws" {
  region              = local.region
  allowed_account_ids = [local.account_id]
}

# Staging records the connector in P0 before the Lambda is deployed.
resource "p0_databricks_ai_connector_staged" "example" {
  id     = local.account_id
  region = local.region
}

# Lets the connector mint AWS identity tokens, which Databricks accepts in place
# of a secret. This is a setting of the whole AWS account: destroying this
# resource turns outbound identity federation off for everything in it. If it
# is already on, import it, with the AWS account ID as its ID, rather than
# create it. To check, run this with AWS CLI 2.32.0 or later:
#   aws iam get-outbound-web-identity-federation-info
# If it's on, the output shows "JwtVendingEnabled": true and the issuer URL as
# IssuerIdentifier. If it's off, the command fails with FeatureDisabled. Import
# it with:
#   terraform import aws_iam_outbound_web_identity_federation.this <account ID>
# To remove the connector but leave federation on, replace this block with a
# removed block (Terraform 1.7+) before you destroy the rest. Terraform then
# forgets the setting without turning it off:
#   removed {
#     from = aws_iam_outbound_web_identity_federation.this
#     lifecycle {
#       destroy = false
#     }
#   }
resource "aws_iam_outbound_web_identity_federation" "this" {}

# The federation policy on P0's service principal in each Databricks account
# trusts this role by its ARN. The p0_databricks_ai_account example finds the
# role by the connector's name.
resource "aws_iam_role" "connector" {
  name = local.connector_name
  tags = local.tags
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect    = "Allow"
      Principal = { Service = "lambda.amazonaws.com" }
      Action    = "sts:AssumeRole"
    }]
  })
}

# The log group Lambda writes the connector's logs to.
resource "aws_cloudwatch_log_group" "connector" {
  name              = "/aws/lambda/${local.connector_name}"
  retention_in_days = local.log_retention_days
  tags              = local.tags
}

# The connector writes its own logs, and no others.
resource "aws_iam_role_policy" "connector_logs" {
  name = "${local.connector_name}-logs"
  role = aws_iam_role.connector.id
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = ["logs:CreateLogStream", "logs:PutLogEvents"]
      Resource = "${aws_cloudwatch_log_group.connector.arn}:*"
    }]
  })
}

# Only tokens for Databricks. Every Databricks federation policy that trusts
# this role expects this audience, "databricks".
resource "aws_iam_role_policy" "connector_identity_token" {
  name = "${local.connector_name}-identity-token"
  role = aws_iam_role.connector.id
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = "sts:GetWebIdentityToken"
      Resource = "*"
      Condition = {
        "ForAllValues:StringEquals" = {
          "sts:IdentityTokenAudience" = [p0_databricks_ai_connector_staged.example.federation_audience]
        }
      }
    }]
  })
}

data "docker_registry_image" "connector" {
  name = "${local.connector_image_name}:${local.connector_image_tag}"

  lifecycle {
    postcondition {
      condition     = self.sha256_digest == local.connector_image_digest
      error_message = "The connector image's tag doesn't resolve to the digest pinned here. Take both from the latest p0_databricks_ai_connector example in P0's Terraform registry docs, or contact support@p0.dev."
    }
  }
}

# Lambda only runs images from Amazon ECR, so this copies P0's image into a
# repository in this account. It needs docker and the AWS CLI, signed in to this
# account, wherever Terraform runs.
resource "aws_ecr_repository" "connector" {
  name = local.connector_name
  # Tags can't be overwritten, so no one who can push to this repository can
  # replace the image that signs in to Databricks as P0's service principal.
  image_tag_mutability = "IMMUTABLE"
  force_delete         = true
  tags                 = local.tags

  image_scanning_configuration {
    scan_on_push = true
  }
}

# Copies the pinned image again whenever its tag or digest changes, tagged
# with the image's tag and this copy's id. ECR's tags can't be overwritten, so
# each copy needs a tag of its own: copying the image again, to roll back or
# after an interrupted apply, pushes a new one.
resource "terraform_data" "connector_image" {
  triggers_replace = {
    digest         = data.docker_registry_image.connector.sha256_digest
    repository_url = aws_ecr_repository.connector.repository_url
    tag            = local.connector_image_tag
  }

  provisioner "local-exec" {
    # Signs Docker out of ECR at the end, so its login doesn't outlast the copy.
    # A failed sign-out doesn't fail the copy once the image is pushed.
    command = <<-EOT
      set -e
      trap 'docker logout "$REGISTRY" || true' EXIT
      aws ecr get-login-password --region "$REGION" |
        docker login --username AWS --password-stdin "$REGISTRY"
      docker pull --platform linux/amd64 "$SOURCE"
      docker tag "$SOURCE" "$TARGET"
      docker push "$TARGET"
    EOT

    environment = {
      REGION   = local.region
      REGISTRY = split("/", aws_ecr_repository.connector.repository_url)[0]
      SOURCE   = "${local.connector_image_name}@${local.connector_image_digest}"
      TARGET   = "${aws_ecr_repository.connector.repository_url}:${local.connector_image_tag}-${self.id}"
    }
  }
}

# Pulling one platform and pushing it can give ECR a different manifest from
# the one the tag names on Docker Hub, so the digest there can differ from the
# one pinned above. Lambda needs ECR's.
data "aws_ecr_image" "connector" {
  repository_name = aws_ecr_repository.connector.name
  image_tag       = "${local.connector_image_tag}-${terraform_data.connector_image.id}"
}

resource "aws_lambda_function" "connector" {
  # P0 invokes the connector by its name in this account and region, so it must
  # be deployed exactly there. If your other AWS providers have credential
  # settings, such as profile or assume_role, add them to the provider above.
  function_name = local.connector_name
  role          = aws_iam_role.connector.arn
  package_type  = "Image"
  image_uri     = "${aws_ecr_repository.connector.repository_url}@${data.aws_ecr_image.connector.image_digest}"
  architectures = ["x86_64"]
  # A revoke hands back ownership of everything the agent created, which on a
  # large catalog takes minutes. P0 stops waiting for the connector after 5
  # minutes and tries again, so the timeout stays under that, or a slow revoke
  # would be retried while it still runs.
  timeout = 270
  tags    = local.tags

  # The connector is staged in P0 before it's deployed. Its role can't create
  # a log group, so its own must exist before it runs.
  depends_on = [
    p0_databricks_ai_connector_staged.example,
    aws_cloudwatch_log_group.connector,
  ]
}

# Lets P0 invoke the connector, through the role P0's AWS IAM management
# assumes in this account.
resource "aws_iam_role_policy" "p0_invoke_connector" {
  name = "${local.connector_name}-invoke"
  role = local.p0_role_name
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = "lambda:InvokeFunction"
      Resource = aws_lambda_function.connector.arn
    }]
  })
}

# Completes the install. P0 checks that it can invoke the connector, retrying
# for about half a minute while a new IAM policy takes effect. If the first
# apply is denied access, apply again.
resource "p0_databricks_ai_connector" "example" {
  id     = p0_databricks_ai_connector_staged.example.id
  region = p0_databricks_ai_connector_staged.example.region

  depends_on = [
    aws_iam_outbound_web_identity_federation.this,
    aws_iam_role_policy.connector_identity_token,
    aws_iam_role_policy.p0_invoke_connector,
  ]
}
```

Step 4 alone is this one resource, from the provider's `p0_databricks_ai_account_staged` example:

```terraform
resource "p0_databricks_ai_account_staged" "example" {
  id           = "01234567-89ab-cdef-0123-456789abcdef"
  connector    = "123456789012"
  accounts_url = "https://accounts.cloud.databricks.com"
}
```

The provider's example for `p0_databricks_ai_account` does steps 4 to 6 for one account in one configuration. Set the values in its `locals`:

```terraform
# Adds a Databricks account: a service principal there that the connector
# exchanges its AWS identity for. The principal is account admin, and metastore
# admin of every metastore in the account through each metastore's admin
# group. Apply it as a Databricks account admin, signed in to the connector's
# AWS account.
# Full chain: p0_databricks_ai_connector -> p0_databricks_ai_account_staged ->
# service principal, federation policy, account admin role and metastore admin
# groups -> p0_databricks_ai_account.

terraform {
  required_providers {
    # 6.36.0 added the aws_iam_outbound_web_identity_federation data source.
    # Referring to the connector's resource instead needs only 6.26.0.
    aws = {
      source  = "hashicorp/aws"
      version = ">= 6.36.0"
    }
    databricks = {
      source  = "databricks/databricks"
      version = ">= 1.115.0"
    }
    # 0.82.0 added the p0_databricks_ai resources.
    p0 = {
      source  = "p0-security/p0"
      version = ">= 0.82.0"
    }
  }
}

locals {
  # The AWS account and region that the connector runs in.
  aws_account_id        = "123456789012"
  aws_region            = "us-east-1"
  databricks_account_id = "01234567-89ab-cdef-0123-456789abcdef"
  accounts_url          = "https://accounts.cloud.databricks.com"

  # The display name of each metastore's admin group. P0's service principal
  # joins each one, which makes it metastore admin. List one group for every
  # metastore in the account.
  metastore_admin_groups = ["metastore-admins"]

  # Who owns what an agent creates once its access ends: a group's display
  # name, a user's userName, or a service principal's application ID.
  owner_principal = "metastore-admins"
}

# Reads the connector's role and issuer, so it must be signed in to the
# connector's AWS account.
provider "aws" {
  region              = local.aws_region
  allowed_account_ids = [local.aws_account_id]
}

# Service principals and their roles live at the account level, so the provider
# must be account-level. Unless told how to sign in, it uses whatever Databricks
# credentials it finds, such as a CLI login, so everyone who plans or applies
# needs their own account admin login. To avoid that, sign it in as a service
# principal with the account_admin role and a federation policy, which needs no
# secret: add auth_type = "env-oidc" and client_id = "<its application ID>", and
# set DATABRICKS_OIDC_TOKEN to an identity token that the policy accepts.
provider "databricks" {
  host       = local.accounts_url
  account_id = local.databricks_account_id
}

# The connector's role, and the issuer of the identity tokens it mints (see the
# p0_databricks_ai_connector example). If this configuration also holds the
# connector, as P0's installer arranges it, refer to the connector's
# aws_iam_role and aws_iam_outbound_web_identity_federation resources instead.
data "aws_iam_role" "connector" {
  name = "p0-connector-databricks-ai"
}

data "aws_iam_outbound_web_identity_federation" "this" {}

resource "p0_databricks_ai_account_staged" "example" {
  id           = local.databricks_account_id
  connector    = local.aws_account_id
  accounts_url = local.accounts_url
}

resource "databricks_service_principal" "p0" {
  display_name = "p0-databricks-ai"
}

# Lets the connector's Lambda role sign in as this principal with an AWS
# identity token, so no secret is ever issued.
resource "databricks_service_principal_federation_policy" "p0" {
  service_principal_id = databricks_service_principal.p0.id
  oidc_policy = {
    issuer    = data.aws_iam_outbound_web_identity_federation.this.issuer_identifier
    subject   = data.aws_iam_role.connector.arn
    audiences = [p0_databricks_ai_account_staged.example.federation_audience]
  }
}

# Account admin lets P0 create a service principal for each agent's request,
# find the account's workspaces, and make itself workspace admin of each one
# an agent uses.
resource "databricks_service_principal_role" "p0_account_admin" {
  service_principal_id = databricks_service_principal.p0.id
  role                 = "account_admin"
}

# Metastore admin lets P0 grant Unity Catalog privileges on any catalog, and
# hand what an agent created to the owner principal when its access ends.
data "databricks_group" "metastore_admins" {
  for_each     = toset(local.metastore_admin_groups)
  display_name = each.value
}

resource "databricks_group_member" "p0_metastore_admin" {
  # Only the IDs, so the group's deprecated attributes stay out of the plan.
  for_each  = { for name, group in data.databricks_group.metastore_admins : name => group.id }
  group_id  = each.value
  member_id = databricks_service_principal.p0.id
}

# Completes the install. P0 checks that the connector can sign in as the
# principal, that the principal is account admin and metastore admin, and that
# owner_principal names one principal in the account.
resource "p0_databricks_ai_account" "example" {
  id              = p0_databricks_ai_account_staged.example.id
  connector       = p0_databricks_ai_account_staged.example.connector
  accounts_url    = p0_databricks_ai_account_staged.example.accounts_url
  application_id  = databricks_service_principal.p0.application_id
  owner_principal = local.owner_principal

  depends_on = [
    databricks_service_principal_federation_policy.p0,
    databricks_service_principal_role.p0_account_admin,
    databricks_group_member.p0_metastore_admin,
  ]
}
```

### Turn on the SQL tools

Databricks' SQL MCP server needs the Unity Gateway beta. An account admin turns it on for the whole account, from the **Previews** page of the account console. See Databricks' [Databricks SQL MCP server](https://docs.databricks.com/aws/en/agents/mcp-tools/databricks-sql).

P0 checks for the beta only when you save the account. If it was off, the account in P0 shows this warning:

> Databricks SQL tools need the Unity Gateway beta. Turn it on in the account console's Previews page, then click Update on this account in P0.

Once you turn the beta on, save the account again in P0 so that P0 sees it. This applies to accounts installed with Terraform too: Terraform doesn't show the warning, and an apply with no changes doesn't save the account. To save it again, open the account on the **Databricks (AI)** integration in P0, and click **Update**.

## Add the Databricks MCP servers

There are two servers:

* **Databricks Genie**: Databricks' Genie tools, which answer questions about data in natural language. You can add it once at least one account is installed.
* **Databricks SQL**: Databricks' SQL tools, which run SQL statements. You can add it once an installed account has the Unity Gateway beta on.

Each server you add covers one workspace. Add a Databricks Genie server and a Databricks SQL server for every workspace agents use.

To add each one:

1. Follow the shared steps in [MCP server](https://docs.p0.dev/agentic-access/agentic-gateway/mcp-server.md#add-an-mcp-server) to name the server and choose its gateway. On the configuration screen, set the following fields, then click **Finish**:
   * **Credential source**: choose **Token exchange (RFC 8693)**.
   * **Definition**: choose **P0**, then select **Databricks Genie** or **Databricks SQL**.
   * **Instance**: the workspace's deployment name, the part of its URL before `.cloud.databricks.com`. For the workspace at `https://dbc-a1b2c3d4-e5f6.cloud.databricks.com`, enter `dbc-a1b2c3d4-e5f6`. It takes lowercase letters, digits, and hyphens.
2. The server now appears with the state **Installed**.

You can't change a server's instance after you add it. To cover another workspace, add another server. Agents see the instance in the server's name, such as **Databricks SQL (dbc-a1b2c3d4-e5f6)**.

## How agents request access

An agent requests access with a server's `access` tool. It names a workspace by its numeric ID, a pro or serverless SQL warehouse in it, a catalog, and a level. To narrow the request, it also names a schema, and then a table or a volume. P0 grants the level on the deepest object named. A table can also be a view or a materialized view. The equivalent CLI request is:

```bash
p0 request databricks-ai data <workspace> <warehouse> <catalog> <level> [--schema <schema>] [--table <table> | --volume <volume>] --reason "<reason>"
```

The level is `read` or `write`:

| Granted on                          | `read` grants                                                   | `write` also grants                                                                                      |
| ----------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| A catalog                           | `USE_CATALOG`, `USE_SCHEMA`, `SELECT`, `READ_VOLUME`, `EXECUTE` | `MODIFY`, `WRITE_VOLUME`, `CREATE_TABLE`, `CREATE_VOLUME`, `CREATE_FUNCTION`, `CREATE_MATERIALIZED_VIEW` |
| A schema                            | `USE_SCHEMA`, `SELECT`, `READ_VOLUME`, `EXECUTE`                | `MODIFY`, `WRITE_VOLUME`, `CREATE_TABLE`, `CREATE_VOLUME`, `CREATE_FUNCTION`, `CREATE_MATERIALIZED_VIEW` |
| A table, view, or materialized view | `SELECT`                                                        | `MODIFY`                                                                                                 |
| A volume                            | `READ_VOLUME`                                                   | `WRITE_VOLUME`                                                                                           |

P0 also grants `USE_CATALOG` and `USE_SCHEMA` on the object's parents, and `CAN USE` on the warehouse.

Agents call Databricks' MCP servers through the `EXECUTE` privilege that `account users` hold on the `system.ai` schema by default. Keep that default in place. What an agent can reach is controlled by its warehouse and Unity Catalog grants.

A grant works only in the gateway session that requested it, and only on the server whose `access` tool requested it. To use both the Genie and the SQL tools, the agent requests access through each server.

P0 refuses a request that came through any server other than an installed Databricks Genie or Databricks SQL server, with this message:

> This request didn't come through an installed Databricks Genie or Databricks SQL server. Request again through one of them.

A server grants access only in the workspace its instance names. P0 refuses a request for any other workspace, with this message:

> This Databricks server covers only the workspace at <https://dbc-a1b2c3d4-e5f6.cloud.databricks.com>, and workspace 1234567890123456 is at <https://dbc-f6e5d4c3-b2a1.cloud.databricks.com>. Request access to workspace 1234567890123456 through the Databricks Genie or Databricks SQL server added for <https://dbc-f6e5d4c3-b2a1.cloud.databricks.com>.

Once a request is approved, access usually works within 30 to 60 seconds, and can take up to two minutes.

When the grant ends, P0 makes the owner principal the owner of every table, view, materialized view, volume, and function the agent's principal owns, then deletes the principal. Before that, P0 deactivates the principal, so the agent gets no new Databricks token, and removes its grants. A token the agent already holds keeps working for up to about 15 minutes after the revoke, with its grants already removed.

See [Requesting access](https://docs.p0.dev/agentic-access/using-the-gateway/requesting-access.md) for how agents submit and use requests.

## Write policies for Databricks

Match Databricks requests in an agentic access policy (see [Agentic access policies](https://docs.p0.dev/agentic-access/agentic-access-policies.md)) with `service: databricks-ai` and `accessType: data`. These filters narrow them:

| Filter      | Key    | What it matches                                                                                                                          | Example                                |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `account`   | `id`   | The Databricks account ID                                                                                                                | `01234567-89ab-cdef-0123-456789abcdef` |
| `workspace` | `id`   | The workspace ID                                                                                                                         | `1234567890123456`                     |
| `workspace` | `name` | The workspace's name in Databricks                                                                                                       | `analytics-prod`                       |
| `catalog`   | `name` | The catalog                                                                                                                              | `main`                                 |
| `schema`    | `name` | The schema, empty for a request on a whole catalog                                                                                       | `sales`                                |
| `securable` | `name` | The full name of the object the level is granted on                                                                                      | `main.sales.orders`                    |
| `securable` | `type` | That object's type: `catalog`, `schema`, `table`, or `volume`. A view or materialized view is a `table`.                                 | `table`                                |
| `privilege` | `name` | Each privilege the level grants on the object, as in the table above. The `USE_CATALOG` and `USE_SCHEMA` on its parents aren't included. | `SELECT`                               |

Policies are the only limit on what agents can request. Every catalog a workspace can use can be requested, except Databricks' own `system` and `__databricks_internal` catalogs, so write a policy for each kind of access you allow.

Match workspaces on `id`: a workspace admin can rename a workspace. Privilege names are in uppercase, and catalog, schema, and securable names are in lowercase.

### Anchor your patterns

Patterns are case-sensitive regular expressions, and they match anywhere in a value. In a pattern, `.` matches any character, so `^main.sales$` also matches a schema named `main_sales`. Write `\.` to match only a dot, as the examples below do.

Start each pattern with `^`, and end it with `$` or `\.`. A pattern without anchors matches more than it looks like it does. `sales` also matches `presales`, and `^main\.sales` also matches `main.sales_archive`.

* `^main\.sales\.` matches every table, view, and volume in the `main.sales` schema, but not the schema itself.
* `^main\.sales(\.|$)` also matches the `main.sales` schema.
* `^main\.sales\.orders$` matches one table.

### Examples

In a rule that allows access, a `keep` filter on `privilege` must match every privilege the request's level grants. So a rule whose `privilege` pattern lists only `read`'s privileges never matches a `write` request.

This policy auto-approves `read` access to the `main.sales` schema and everything in it, for one agent, in one workspace:

```yaml
- requestor:
    type: agentic
    actor:
      type: agent-client
      clientId: reporting-agent
    subject:
      type: any
  resource:
    type: integration
    service: databricks-ai
    accessType: data
    filters:
      workspace:
        effect: keep
        key: id
        pattern: ^1234567890123456$
      securable:
        effect: keep
        key: name
        pattern: ^main\.sales(\.|$)
      privilege:
        effect: keep
        key: name
        pattern: ^(USE_SCHEMA|SELECT|READ_VOLUME|EXECUTE)$
  approval:
    - type: persistent
```

Add this policy to send every other request on `main.sales` from any agent, `write` included, to your Security Reviewers. A `read` request from `reporting-agent` matches both policies, and the first approves it.

```yaml
- requestor:
    type: agentic
    actor:
      type: any
    subject:
      type: any
  resource:
    type: integration
    service: databricks-ai
    accessType: data
    filters:
      workspace:
        effect: keep
        key: id
        pattern: ^1234567890123456$
      securable:
        effect: keep
        key: name
        pattern: ^main\.sales(\.|$)
  approval:
    - type: p0
```

### Make the SQL tools read-only

Databricks' SQL MCP server allows reads and writes. To make it read-only for every agent, whatever level they hold, set `disallow_writes` to `true` in the built-in `system.ai.dbsql_policy` policy. See Databricks' [Databricks SQL MCP server](https://docs.databricks.com/aws/en/agents/mcp-tools/databricks-sql).

## Leftover principals

An agent's service principal, named `p0-agent-<request ID>`, can stay in your account in two cases:

* **A revoke failed.** P0 deactivates the principal before it removes any grant, so the principal stays deactivated.
* **A request failed after P0 created its principal.** The principal is active, but bare: it has no federation policy.

Before you delete one in the account console:

1. Hand anything the principal owns to your owner principal.
2. Have a metastore admin revoke every privilege the principal holds. If its workspace was deleted, do this from another workspace on the same metastore.

Delete one only once its request has ended or shows an error in P0. A revoke for a workspace that was deleted can't finish, so its request stays errored in P0.

## Remove the integration

1. **Remove the Databricks MCP servers** from your gateway.
2. **End or revoke every active grant**, so that P0 deletes each agent's service principal. Then delete any leftover principals, as in [#leftover-principals](#leftover-principals "mention").
3. **Delete each account and the connector** from the **Databricks (AI)** integration in P0.
4. **Destroy the Terraform configuration** with `terraform destroy`. This deletes P0's service principal, so P0 can no longer sign in to the account. To keep outbound web identity federation on in the AWS account, replace its resource with the `removed` block in the Terraform's comments before you destroy.

## Next steps

* Define the [Agentic access policies](https://docs.p0.dev/agentic-access/agentic-access-policies.md) that decide which agents and users can request Databricks access.
