# Sidecar Docs Source: https://docs.sidecardata.com/index Get started with Sidecar by connecting your data stack ## What is Sidecar? Sidecar is a data catalog that connects to your entire data stack — dbt, Snowflake, BigQuery, Looker, and more — to give your team a unified view of your data assets, lineage, and metadata. ## Connect Your Data Stack Each integration guide walks you through setup step by step. Create, version, and serve semantic context for analytics and AI tools Run autonomous agents like Builder against your repositories, with human-approved delivery Connect Snowflake, BigQuery, Redshift, or Databricks Connect dbt Cloud or dbt Core Connect Looker, Metabase, Lightdash, Omni, or Power BI Connect Fivetran Connect Slack or Microsoft Teams Connect Jira or Linear ## Metadata-Only Access By default, Sidecar operates in a metadata-only mode. This means Sidecar does not query or access the underlying data in your warehouse. Instead, we work with metadata about your stack, such as: * Table and column names * Schema structure * Lineage and dependencies * dbt metadata * Query history metadata * Operational signals and usage patterns Our goal is to build context about how your data platform works without requiring access to the data itself. ### Exceptions The primary exception is optional automated dbt test generation. If enabled, Sidecar may query limited warehouse data in order to automatically generate and validate common dbt tests, including: * Primary key tests * Not null tests * Unique tests * Accepted values tests This functionality is optional and can be disabled at any time. ### Business Context Integrations Sidecar can also integrate with tools like Slack and Jira. These integrations help enrich the context layer with institutional and business knowledge that typically does not exist in metadata alone. In some cases, Slack may also be used purely for operational notifications and alert delivery. In those scenarios, Sidecar does not need to ingest Slack conversation history or message content. When enabled for contextual enrichment, data from these systems is used solely to improve discovery, lineage understanding, operational awareness, and AI-assisted workflows within Sidecar. These context-enrichment capabilities can be disabled if preferred. ## Need Help? If you run into any issues during setup, reach out to us at [support@sidecardata.com](mailto:support@sidecardata.com) or via your dedicated Slack channel. # Lightdash Source: https://docs.sidecardata.com/integrations/bi-analytics/lightdash Connect your Lightdash project to Sidecar ## Requirements * A Lightdash account for your organization * A Lightdash project to integrate with Sidecar * A Lightdash Personal Access Token (PAT) ## 1. Get your Instance URL and Project ID Navigate to the general settings for your Lightdash project. The settings can be accessed by clicking the gear icon or directly via URL: ``` https://{your_instance_url}/generalSettings/projectManagement/{your_project_uuid}/settings ``` ## 2. Create a Personal Access Token Sidecar needs a PAT to interact with the Lightdash API on your organization's behalf. 1. Navigate to the Personal Access Tokens page: ``` https://{your_instance_url}/generalSettings/personalAccessTokens ``` 2. Create a new token. It is recommended that the PAT you configure for Sidecar is created with **no expiration date**. Save the PAT in a password manager — after you navigate away, you cannot view it again. ## 3. Connect Lightdash to Sidecar 1. Go to the **Integrations** page in Sidecar. 2. Find and click on the **Lightdash** integration under "Browse integrations". 3. Enter your **Instance URL**, **Project ID**, and **PAT**. 4. Click **Test** then **Save**. # Looker Source: https://docs.sidecardata.com/integrations/bi-analytics/looker Connect your Looker instance to Sidecar ## Setup 1. Follow [Looker's instructions](https://cloud.google.com/looker/docs/api-auth) to create a Looker **API Client ID** and **Client Secret**. 2. On Sidecar's Looker Integration page, provide the following details: | Field | Description | | ----------------- | ----------------------------------------------------------------------------------- | | **Base URL** | The domain for your Looker instance (e.g., `https://company_name.cloud.looker.com`) | | **Client ID** | From Step 1 | | **Client Secret** | From Step 1 | 3. Click **Test** then **Save**. # Metabase Source: https://docs.sidecardata.com/integrations/bi-analytics/metabase Connect your Metabase instance to Sidecar ## 1. Create a Metabase API key 1. Click the gear icon in the top right, then select **Admin settings**. 2. In the left-hand menu, click on **Settings**, then **Authentication**. 3. Scroll down to the **API Keys** section and click the **Manage** button. 4. Click the **Create API Key** button. 5. Create a new API Key: * **Key name:** Give it a descriptive name (e.g., `Sidecar`) * **Select a Group:** Select **Administrator** 6. Copy the value displayed on the screen. The API key will not be visible again after you leave the page. Save it somewhere safe. ## 2. Connect Metabase to Sidecar 1. In the Integrations page, navigate to the `Metabase` integration. 2. In the `Metabase URL` field, input your Metabase URL (e.g., `https://your_account.metabaseapp.com`). 3. In the `API Key` field, input the key you copied in Step 1. 4. Click `Test` then `Save`. # Omni Source: https://docs.sidecardata.com/integrations/bi-analytics/omni Connect your Omni workspace to Sidecar ## 1. Create an API Key 1. Log in to your **Omni** console. 2. Navigate to **User Settings** > **API Keys**. 3. Click **Generate New Token** and copy the token to a secure location. This token will be used as your **API Key** when setting up the integration. ## 2. Connect Omni to Sidecar In the Sidecar integration setup screen, enter the following credentials: | Field | Description | | ----------- | ----------------------------------------------------------------------- | | **Host** | The URL of your Omni workspace (e.g., `https://yourcompany.omniapp.co`) | | **API Key** | The token you generated in Step 1 | Click **Test Connection**. If the connection is successful, click **Save**. # Power BI Source: https://docs.sidecardata.com/integrations/bi-analytics/power-bi Connect Microsoft Power BI to Sidecar ## Prerequisites * Admin access to **Microsoft Entra ID** (formerly Azure AD) * Admin access to **Microsoft Fabric** (formerly Power BI Admin Portal) ## Overview 1. Create an Azure app 2. Create a security group in Microsoft Entra ID 3. Enable Power BI service admin settings 4. Add the Azure app to your workspaces 5. Connect Power BI to Sidecar ## 1. Create an Azure app 1. Open the [Azure Portal](https://ms.portal.azure.com/#allservices) and sign in. 2. Search for **App registrations** and select it. 3. Click **New registration**. 4. Fill in the required information: * **Name:** `Sidecar Data` * **Supported account types:** leave the default ("Accounts in this organizational directory only — Single tenant") * **Redirect URI:** leave empty 5. Click **Register**. 6. From the Overview page, copy the **Application (client) ID** and **Directory (tenant) ID**. Store them securely. 7. Click **Certificates & secrets** from the left menu. 8. Under Client secrets, click **+ New client secret**. 9. Enter a description, select an expiry time, and click **Add**. 10. Copy the client secret **Value** and store it securely. ## 2. Create a security group in Microsoft Entra ID 1. Open the [Azure Portal](https://ms.portal.azure.com/#allservices) and sign in. 2. Search for **Microsoft Entra ID** and select it. 3. Click **Groups** under the Manage section. 4. Click **New group**. 5. Fill in: * **Group type:** Security * **Name:** `Power BI - API Access` 6. Click "No members selected", search for **Sidecar Data**, and select it. 7. Click **Create**. ## 3. Enable Power BI service admin settings 1. Open the [Power BI admin portal](https://app.powerbi.com/admin-portal/) and sign in. 2. Click **Tenant Settings** under the Admin Portal. 3. Under **Developer settings**, expand **Service principals can call Fabric public APIs**: * Set to **Enabled** * Add your security group from Step 2 under **Specific security groups** * Click **Apply** 4. Repeat for the following sections under **Admin API settings**: * Service principals can access read-only admin APIs * Enhance admin APIs responses with detailed metadata * Enhance admin APIs responses with DAX and mashup expressions ## 4. Add the Azure app to your workspaces 1. Open [Power BI](https://app.powerbi.com/) and sign in. 2. For each workspace you want Sidecar to access: 1. From the workspace menu, select **Workspace access**. 2. Click **+ Add people or groups**. 3. Search for **Sidecar Data**, set permissions to **Contributor**. 4. Click **Add**. If you have Power BI reports using Semantic Models from other workspaces, add the Azure App as a **Contributor** to those workspaces as well. This is required for column-level lineage. ## 5. Connect Power BI to Sidecar Provide the following information to the Sidecar team: | Field | Description | | ----------------- | ----------------------------------- | | **Client ID** | Application (client) ID from Step 1 | | **Client Secret** | Client secret value from Step 1 | | **Tenant ID** | Directory (tenant) ID from Step 1 | # Microsoft Teams Source: https://docs.sidecardata.com/integrations/communication/ms-teams Connect Microsoft Teams to Sidecar ## 1. Grant permissions 1. Go to the **Settings** page in Sidecar, select the **Microsoft Teams** tab. 2. Press `Connect now`. 3. A new tab will open requesting permissions. This is only used to get your tenant ID. 4. After you accept, you will be redirected back to Sidecar. 5. Select **Return to Integration Page**. ## 2. Install the Sidecar App in Teams 1. Open Teams, select **Apps**, then choose **Manage your apps**. 2. Select **Upload an app**. 3. Choose **Upload a custom app**, then select the `sidecar.zip` file provided by the Sidecar team. 4. After uploading, the Sidecar app will appear in your apps list. 5. Click **Add**, and choose the **General** channel. This step only registers your team — the bot will not send notifications to this channel. ## 3. Configure bot notifications 1. Back in the Sidecar app, go to the **Teams** settings. 2. Select the channel where you want the bot to send alerts. 3. Press **Save**. When a dbt job fails, the bot will send an alert to the configured channel. # Slack Source: https://docs.sidecardata.com/integrations/communication/slack Connect your Slack workspace to Sidecar ## Connect the Sidecar Slack app In the Sidecar app, go to the **Integrations** section from the sidebar. Scroll down or search for **Slack**, then click into it. Click **Connect now**. You will be redirected to a page where you can confirm the workspace you want to integrate with. Click **Allow** to add the Sidecar Slack App to your workspace. Agent Console runs start only from direct messages to the Sidecar Slack app. Adding Sidecar to a channel does not enable Agent Console requests there. See [Run an agent from Slack](/products/agent-console/run-an-agent-from-slack). ## Add Sidecar to channels Adding the Sidecar Slack App to channels enables **Slack thread anchoring** — conversations about data assets are automatically linked in the Sidecar catalog. Sidecar only supports anchoring for **public channels** to which the Sidecar App has been added. To add Sidecar to a channel: 1. Navigate to the channel in Slack. 2. Click the icon in the top-right that shows channel participants. 3. Click the **Integrations** tab. 4. Click **Add an App**, find the **Sidecar** app, and add it. Repeat for all channels where you want Sidecar to listen. # BigQuery Source: https://docs.sidecardata.com/integrations/data-warehouses/bigquery Connect your Google BigQuery project to Sidecar ## Prerequisites You'll need to create a custom role and service account in GCP. This role and service account must be added to each Project you want Sidecar to ingest metadata for. ## 1. Setting up a role and service account ### Create a custom role in GCP 1. Navigate to `Roles` in the `IAM & Admin` section. 2. Click the `+ Create Role` button. 3. Give the new role a name such as `Sidecar Data BigQuery`. 4. Click `+ Add Permissions`, and add the following permissions: | # | Permission | Reason | | -- | ------------------------------- | --------------------------------------------------------- | | 1 | `bigquery.datasets.create` | Sidecar dataset setup | | 2 | `bigquery.datasets.get` | Metadata Ingestion | | 3 | `bigquery.tables.get` | Metadata Ingestion | | 4 | `bigquery.tables.getData` | Metadata Ingestion | | 5 | `bigquery.tables.list` | Metadata Ingestion | | 6 | `resourcemanager.projects.get` | Metadata Ingestion | | 7 | `bigquery.jobs.create` | Metadata Ingestion | | 8 | `bigquery.jobs.listAll` | Metadata Ingestion | | 9 | `bigquery.routines.get` | Stored Procedure | | 10 | `bigquery.routines.list` | Stored Procedure | | 11 | `bigquery.readsessions.create` | Usage & Lineage Workflow | | 12 | `bigquery.readsessions.getData` | Usage & Lineage Workflow | | 13 | `logging.operations.list` | Incremental Metadata Ingestion | | 14 | `serviceusage.services.use` | Use the service account project for API quota and billing | | 15 | `mcp.tools.call` | MCP tool calls for Agent Console jobs | `serviceusage.services.use` lets Sidecar use the service account project for API quota and billing. Keep it in this custom role; no additional IAM role is required for this access. 5. Click `Create` to create the role. 6. Repeat the role creation process for each Project you want Sidecar to ingest metadata for. ### Create a service account 1. Navigate to `Service accounts` in the `IAM & Admin` section. 2. Click `+ Create Service Account`. 3. Give the new service account a name like `sidecar-data`. 4. Under "Grant this service account access to project", select the custom role you created above. 5. Click `Done`. 6. For all other Projects you want Sidecar to ingest metadata for: 1. Navigate to `IAM` in the `IAM & Admin` section. 2. Click `+ Grant Access`. 3. Under "Add principals", enter the email address generated for the service account. 4. Under "Assign roles", select the custom role you created. 5. Click `Save`. Replace the `PROJECTS`, `ROLE_ID`, `ROLE_TITLE`, and `ROLE_DESCRIPTION` with your own values: ```bash theme={null} #!/bin/bash PROJECTS=("project-1-id" "project-2-id" "project-3-id") ROLE_ID="sidecarDataBigQuery" ROLE_TITLE="SidecarData BigQuery" ROLE_DESCRIPTION="Custom IAM role for Sidecar's service account to access BigQuery" PERMISSIONS=( "bigquery.datasets.create", "bigquery.datasets.get", "bigquery.tables.get", "bigquery.tables.getData", "bigquery.tables.list", "resourcemanager.projects.get", "bigquery.jobs.create", "bigquery.jobs.listAll", "bigquery.routines.get", "bigquery.routines.list", "bigquery.readsessions.create", "bigquery.readsessions.getData", "logging.operations.list", "serviceusage.services.use", "mcp.tools.call", ) PERMISSIONS_CSV=$(IFS=,; echo "${PERMISSIONS[*]}") for PROJECT in "${PROJECTS[@]}"; do echo "Creating IAM role in project: $PROJECT" gcloud iam roles create $ROLE_ID \ --project="$PROJECT" \ --title="$ROLE_TITLE" \ --description="$ROLE_DESCRIPTION" \ --permissions="$PERMISSIONS_CSV" \ --stage="GA" echo "IAM role created successfully in project: $PROJECT" done echo "IAM role creation process completed!" ``` ## 2. Create and download key credentials 1. For your primary Project, navigate to `Service accounts` in the `IAM & Credentials` section. 2. Find the service account you created for Sidecar, click the 3 dots and click `Manage keys`. 3. Click `Add key`, then `Create new key`. 4. Select **JSON** as the Key type. 5. Click `Create`. This will download a JSON file to your machine. ## 3. Upload your service account key to Sidecar 1. In the Onboarding page (or Account Settings), navigate to "Connect your data warehouse" and select "BigQuery". 2. Select the downloaded JSON key file from Step 2. 3. Click `Test` then `Save`. ## 4. Additional permissions * **Cloud Resource Manager API** and **Cloud Asset API** must be enabled. * Add the `Cloud Asset Viewer` role to the Sidecar service account. ## 5. Optional Storage Read API activity Spark, Dataproc, and other clients can read BigQuery tables through the Storage Read API without creating a query job. Complete this setup if you want Sidecar to treat those direct reads as activity when evaluating query activity. Sidecar reads from one dedicated Cloud Logging view for each BigQuery integration. The view must receive matching events from every project that owns BigQuery tables selected in Sidecar. Reuse the service account and JSON key from steps 1–3. You don't need a new service account or key. The existing `logging.operations.list` permission does not grant access to Data Access logs. Logging sinks route only new log entries. Creating a sink with 90-day retention does not backfill the previous 90 days. Existing recommendations might remain until the affected table is read again. ### Before you begin Gather the following values: * **Sidecar service account email:** the `client_email` in the JSON key you uploaded to Sidecar. * **BigQuery project IDs:** every project that owns tables selected in the Sidecar integration. * **Logging project ID:** the project that will own the dedicated log bucket and view. For one BigQuery project, use that same project. * **Retention period:** use at least 90 days. If your Sidecar deprecation inactivity threshold is longer than 90 days, use at least that threshold plus one day. Enable `logging.googleapis.com` in the logging project and in the service account's project (`project_id` in the JSON key). These are often the same project. Ensure the Sidecar custom role is granted to the service account in that project and includes `serviceusage.services.use`. If the custom role was created only in other projects, create or update the same project-level custom role here and grant it to the Sidecar service account. No other Service Usage permissions are required for this setup. ### Create the log bucket 1. Select the logging project in the Google Cloud Console. 2. Open **APIs & Services → Library → Cloud Logging API** and click **Enable** if the API isn't already enabled. 3. Open **Logging → Logs Storage** and click **Create log bucket**. 4. Enter `sidecar-bigquery-storage-reads` as the bucket name. 5. Choose a location and record it. The location can't be changed later. 6. Set the retention period determined above. 7. Leave **Upgrade to use Observability Analytics** unchecked. Sidecar doesn't require it. 8. Click **Create bucket**. Google Cloud charges additional retention costs for logs kept longer than 30 days. ### Route Storage API reads into the bucket Repeat these steps in every BigQuery project selected in Sidecar: 1. Select the BigQuery project in the Google Cloud Console. 2. Open **Logging → Log Router** and click **Create sink**. 3. Enter `sidecar-bigquery-storage-reads` as the sink name. 4. Choose **Cloud Logging bucket** as the sink service. 5. Select the dedicated bucket. If the bucket is in another project, use its full destination: ```text theme={null} logging.googleapis.com/projects/LOGGING_PROJECT_ID/locations/LOCATION/buckets/sidecar-bigquery-storage-reads ``` 6. In **Build inclusion filter**, enter: ```text theme={null} log_id("cloudaudit.googleapis.com/data_access") resource.type="bigquery_table" protoPayload.methodName="google.cloud.bigquery.storage.v1.BigQueryRead.ReadRows" ``` 7. Add no exclusion filters and click **Create sink**. 8. If the bucket is in a different project, open the sink details and copy its writer identity. In the logging project, grant that identity **Logs Bucket Writer** (`roles/logging.bucketWriter`). A same-project destination doesn't need this grant. A project-level sink sees only logs that originate in that project. The Spark or Dataproc execution project isn't a substitute for a project that owns selected BigQuery tables. ### Create the restricted log view 1. Return to **Logging → Logs Storage** in the logging project. 2. Open the `sidecar-bigquery-storage-reads` bucket. 3. Under **Log views**, click **Create log view**. 4. Enter `sidecar-bigquery-storage-reads` as the view name. 5. Enter this view filter: ```text theme={null} log_id("cloudaudit.googleapis.com/data_access") AND resource.type="bigquery_table" ``` 6. Save the view. 7. From the view's **Actions** menu, select **Adjust permissions**. 8. Add the Sidecar service account email and assign **Logs View Accessor** (`roles/logging.viewAccessor`). Grant the role on the view itself. Don't grant Sidecar `roles/logging.privateLogViewer`, project-level `roles/logging.viewAccessor`, `roles/logging.bucketWriter`, or a Logging administration role. The following example supports one or more BigQuery projects. Every source project routes matching events into one bucket and view. ```hcl theme={null} variable "logging_project_id" { type = string } variable "logging_location" { type = string default = "global" } variable "bigquery_project_ids" { type = set(string) } variable "sidecar_service_account_email" { type = string } variable "retention_days" { type = number default = 90 } locals { logging_api_projects = setunion( var.bigquery_project_ids, toset([var.logging_project_id]), ) } resource "google_project_service" "logging" { for_each = local.logging_api_projects project = each.value service = "logging.googleapis.com" disable_on_destroy = false } resource "google_logging_project_bucket_config" "sidecar_storage_reads" { project = var.logging_project_id location = var.logging_location bucket_id = "sidecar-bigquery-storage-reads" retention_days = var.retention_days depends_on = [google_project_service.logging] } resource "google_logging_project_sink" "sidecar_storage_reads" { for_each = var.bigquery_project_ids project = each.value name = "sidecar-bigquery-storage-reads" destination = "logging.googleapis.com/${google_logging_project_bucket_config.sidecar_storage_reads.id}" filter = <<-EOT log_id("cloudaudit.googleapis.com/data_access") resource.type="bigquery_table" protoPayload.methodName="google.cloud.bigquery.storage.v1.BigQueryRead.ReadRows" EOT unique_writer_identity = each.value != var.logging_project_id } locals { cross_project_sink_writers = { for project_id, sink in google_logging_project_sink.sidecar_storage_reads : project_id => sink.writer_identity if project_id != var.logging_project_id } } resource "google_project_iam_member" "cross_project_sink_writer" { for_each = local.cross_project_sink_writers project = var.logging_project_id role = "roles/logging.bucketWriter" member = each.value } resource "google_logging_log_view" "sidecar_storage_reads" { name = "sidecar-bigquery-storage-reads" bucket = google_logging_project_bucket_config.sidecar_storage_reads.id filter = <<-EOT log_id("cloudaudit.googleapis.com/data_access") AND resource.type="bigquery_table" EOT } resource "google_logging_log_view_iam_member" "sidecar" { parent = "projects/${var.logging_project_id}" location = var.logging_location bucket = google_logging_project_bucket_config.sidecar_storage_reads.bucket_id name = google_logging_log_view.sidecar_storage_reads.name role = "roles/logging.viewAccessor" member = "serviceAccount:${var.sidecar_service_account_email}" } output "sidecar_storage_read_log_view_resource_name" { value = google_logging_log_view.sidecar_storage_reads.id } ``` If the service account's project (`project_id` in the JSON key) isn't included above, enable `logging.googleapis.com` there separately. Create or update the Sidecar project-level custom role in that project so it includes `serviceusage.services.use`, then grant that custom role to the Sidecar service account. No other Service Usage permissions are required for this setup. ### Add the view to Sidecar Copy the complete view resource name. It has this format: ```text theme={null} projects/LOGGING_PROJECT_ID/locations/LOCATION/buckets/sidecar-bigquery-storage-reads/views/sidecar-bigquery-storage-reads ``` In Sidecar, open **Integrations → BigQuery**, enter this value in **Storage Read LogView resource name**, and click **Save**. Enter the full resource name, not a Google Cloud Console URL or a project ID. ### Verify the view After a new Spark or direct Storage API read completes, run this command in Cloud Shell: ```bash theme={null} gcloud logging read \ 'protoPayload.methodName="google.cloud.bigquery.storage.v1.BigQueryRead.ReadRows"' \ --project=LOGGING_PROJECT_ID \ --bucket=sidecar-bigquery-storage-reads \ --location=LOCATION \ --view=sidecar-bigquery-storage-reads \ --freshness=1d \ --limit=10 ``` Sink and IAM changes can take several minutes to propagate. If your organization uses intercepting sinks, confirm that a fresh test read reaches this dedicated view. Learn more in Google's guides to [route logs](https://docs.cloud.google.com/logging/docs/export/configure_export_v2), [manage log buckets](https://docs.cloud.google.com/logging/docs/buckets), and [configure log views](https://docs.cloud.google.com/logging/docs/logs-views). ## Add BigQuery MCP to Agent Console The warehouse connection above does not automatically provide query tools to agents. The `mcp.tools.call` permission in the custom role enables Google's managed MCP servers. Follow [Set up BigQuery MCP](/integrations/mcp-servers/bigquery) to confirm the connection. # Databricks Source: https://docs.sidecardata.com/integrations/data-warehouses/databricks Connect your Databricks workspace to Sidecar ## Prerequisites Before starting, make sure you have: * Access to a **Databricks workspace** * A workspace admin who can create or assign a service principal * Permission to grant **Can use** on a **SQL warehouse** * Access to **Unity Catalog** resources (catalogs, schemas, tables) that you want Sidecar to discover * A catalog owner, metastore admin, or another principal that can grant Unity Catalog privileges * An account admin or metastore admin if the required `system` schemas are not enabled * **Can manage** access to each AI/BI dashboard that you want Sidecar to discover ## 1. Get the host and HTTP path 1. Log in to your **Databricks workspace**. 2. Navigate to **SQL Warehouses**. 3. Select the **SQL Warehouse** you want to use for the integration. 4. Click **Connection details**. Copy the following values: **Server Hostname** — use this as the **Host**: ``` dbc-xxxxxxxx.cloud.databricks.com ``` **HTTP Path** — use this as the **HTTP Path**: ``` /sql/1.0/warehouses/xxxxxxxxxxxx ``` ## 2. Create a service principal and OAuth secret 1. Click your username in the top bar and select **Settings**. 2. Click the **Identity and access** tab. 3. Next to **Service principals**, click **Manage**. 4. Create a new service principal for Sidecar. Creating it from the workspace assigns it to that workspace. 5. Click the created service principal, then click the **Secrets** tab. 6. Click **Generate secret**. 7. Set the secret's lifetime in days (maximum 730 days). 8. Click **Generate**. 9. Copy the displayed **secret** and **client ID**, then click **Done**. The secret is shown only once. The client ID is the same as the service principal's application ID. Use this one OAuth service principal for Sidecar's SQL and workspace API access. Do not create a personal access token (PAT) for this integration. If you reuse an account-level service principal, assign it to this workspace before continuing. ## 3. Grant permissions Grant your Sidecar **service principal** (the OAuth identity from step 2) the following before you test or save the integration in Sidecar. In the SQL commands below, replace `` with the service principal's application ID, which is the **Client ID** you copied in step 2. Keep the surrounding backticks. ### Grant SQL warehouse access In **Settings** → **Identity and access** → **Service principals** → **Manage**, open the Sidecar service principal and confirm that the **Databricks SQL access** entitlement is enabled. In **SQL Warehouses** → your warehouse → **Permissions**, add the service principal with **Can use**. ### Grant access to catalogs Sidecar should scan For each Unity Catalog catalog Sidecar should discover besides `system`, run the following commands. Replace `` and ``. ```sql theme={null} GRANT USE CATALOG ON CATALOG `` TO ``; GRANT USE SCHEMA ON CATALOG `` TO ``; GRANT SELECT ON CATALOG `` TO ``; ``` These catalog-level grants let Sidecar discover and describe all current and future schemas, tables, and views in that catalog. To grant narrower access, grant `USE CATALOG` on the catalog and grant `USE SCHEMA` and `SELECT` only on the schemas or objects Sidecar should scan. ### Grant access to required system tables Sidecar reads the following system data: * `system.information_schema` for catalogs, schemas, tables, views, and columns * `system.access.table_lineage` and `system.access.column_lineage` for lineage * `system.query.history` for query activity * `system.billing.usage` and `system.billing.list_prices` for compute costs In **Catalog Explorer**, confirm that the `access`, `query`, and `billing` schemas exist under the `system` catalog. If one is missing, ask an account admin or metastore admin to [enable that system schema](https://docs.databricks.com/aws/en/admin/system-tables/). Then run the following commands. Replace ``. ```sql theme={null} GRANT USE CATALOG ON CATALOG system TO ``; GRANT USE SCHEMA ON SCHEMA system.information_schema TO ``; GRANT USE SCHEMA ON SCHEMA system.access TO ``; GRANT SELECT ON TABLE system.access.table_lineage TO ``; GRANT SELECT ON TABLE system.access.column_lineage TO ``; GRANT USE SCHEMA ON SCHEMA system.query TO ``; GRANT SELECT ON TABLE system.query.history TO ``; GRANT USE SCHEMA ON SCHEMA system.billing TO ``; GRANT SELECT ON TABLE system.billing.usage TO ``; GRANT SELECT ON TABLE system.billing.list_prices TO ``; ``` ### Create Sidecar's write namespace Sidecar stores derived metadata in the dedicated `sidecar.default` namespace. Ask a metastore admin or a principal with `CREATE CATALOG` on the metastore to run the following commands before you save the integration. If the `sidecar` catalog already exists, its owner can create the schema and grant access. Replace ``. ```sql theme={null} CREATE CATALOG IF NOT EXISTS sidecar; CREATE SCHEMA IF NOT EXISTS sidecar.default; GRANT USE CATALOG ON CATALOG sidecar TO ``; GRANT USE SCHEMA, CREATE TABLE ON SCHEMA sidecar.default TO ``; ``` Sidecar owns the tables and views that it creates in this schema. Do not use this schema for customer-managed objects. ### Share AI/BI dashboards with Sidecar For each AI/BI dashboard that Sidecar should discover: 1. Open the dashboard and click **Share**. 2. Add the Sidecar service principal. 3. Grant **Can view**. Only dashboards visible to the service principal can appear in Sidecar. ## 4. Configure the integration Enter the following information in the Sidecar integration setup page: | Field | Description | | ----------------- | -------------------------- | | **Host** | Databricks Server Hostname | | **HTTP Path** | SQL Warehouse HTTP Path | | **Client ID** | Client ID of OAuth Secret | | **Client Secret** | Secret of OAuth Secret | After entering the credentials: 1. Click **Test Connection**. 2. Click **Save** to finish the integration. **Test Connection** currently verifies OAuth access to the SQL warehouse only. It does not verify system-table grants, the Sidecar write namespace, or AI/BI dashboard access. Complete every applicable grant above before you save the integration. ## Result After the integration is complete, Sidecar will be able to: * Connect to your **Databricks SQL Warehouse** * Discover **catalogs, schemas, and tables** * Discover shared **AI/BI dashboards** * Query metadata from **Unity Catalog** * Use `system` catalog data for **query history**, **lineage**, and **billing** * Store derived metadata in `sidecar.default` ## Add Databricks MCP to Agent Console The warehouse connection above does not automatically provide Databricks tools to agents. Follow [Set up Databricks MCP](/integrations/mcp-servers/databricks) to register a managed MCP server. # Redshift Source: https://docs.sidecardata.com/integrations/data-warehouses/redshift Connect your Amazon Redshift cluster to Sidecar ## Prerequisites To create the read-only service user for Sidecar, you will need admin credentials to your Redshift cluster. ## 1. Create a user and group As a super user, execute the following SQL script: ```sql theme={null} -- Create Sidecar user and group CREATE USER sidecar_user PASSWORD 'changehere' SYSLOG ACCESS UNRESTRICTED; ALTER USER sidecar_user SYSLOG ACCESS UNRESTRICTED; CREATE GROUP sidecar_group; ALTER GROUP sidecar_group ADD USER sidecar_user; -- Grant select to system table GRANT SELECT ON svv_table_info TO GROUP sidecar_group; ``` * `SYSLOG` permissions allow Sidecar to read query logs from all users. * `SELECT` permissions on **SVV\_TABLE\_INFO** allow Sidecar to read metadata about tables in your warehouse. ## 2. Grant permissions to schemas For each schema you want Sidecar to monitor: ```sql theme={null} GRANT USAGE ON SCHEMA "schema" TO GROUP sidecar_group; GRANT SELECT ON ALL TABLES IN SCHEMA "schema" TO GROUP sidecar_group; ALTER DEFAULT PRIVILEGES IN SCHEMA "schema" GRANT SELECT ON TABLES TO GROUP sidecar_group; ``` ```sql theme={null} SELECT 'GRANT USAGE ON SCHEMA "' || schema_name || '" TO GROUP sidecar_group;' || E'\n' || 'GRANT SELECT ON ALL TABLES IN SCHEMA "' || schema_name || '" TO GROUP sidecar_group;' || E'\n' || 'ALTER DEFAULT PRIVILEGES IN SCHEMA "' || schema_name || '" GRANT SELECT ON TABLES TO GROUP sidecar_group;' AS single_schema_statement FROM svv_all_schemas WHERE schema_name NOT IN ('information_schema', 'pg_catalog', 'pg_internal'); ``` Default privileges set for ETL users ensure Sidecar maintains access to tables as ETL jobs run and create/update tables. ## Complete setup script ```sql theme={null} -- Create Sidecar user and group CREATE USER sidecar_user PASSWORD 'Sidecar_redshift123' SYSLOG ACCESS UNRESTRICTED; ALTER USER sidecar_user SYSLOG ACCESS UNRESTRICTED; CREATE GROUP sidecar_group; ALTER GROUP sidecar_group ADD USER sidecar_user; -- Grant select to system table GRANT SELECT ON svv_table_info TO GROUP sidecar_group; -- Create schema for Sidecar CREATE SCHEMA IF NOT EXISTS sidecar AUTHORIZATION sidecar_user; GRANT USAGE, CREATE ON SCHEMA sidecar TO GROUP sidecar_group; -- Generate grant statements for all user schemas SELECT 'GRANT USAGE ON SCHEMA "' || schema_name || '" TO GROUP sidecar_group;' || E'\n' || 'GRANT SELECT ON ALL TABLES IN SCHEMA "' || schema_name || '" TO GROUP sidecar_group;' || E'\n' || 'ALTER DEFAULT PRIVILEGES IN SCHEMA "' || schema_name || '" GRANT SELECT ON TABLES TO GROUP sidecar_group;' AS single_schema_statement FROM svv_all_schemas WHERE schema_name NOT IN ('information_schema', 'pg_catalog', 'pg_internal'); ``` ## Whitelist Sidecar IPs If you restrict Redshift access based on IP: 1. Open the security groups for your Redshift cluster (VPC or EC2 subnet). 2. Add an inbound rule: * **Port Range:** your Redshift port (default: `5439`) * **Source IP:** `44.236.246.98` ## Add Redshift MCP to Agent Console The warehouse connection above does not automatically provide Redshift tools to agents. Follow [Set up Redshift MCP](/integrations/mcp-servers/redshift) to host and register a compatible remote endpoint. # Snowflake Source: https://docs.sidecardata.com/integrations/data-warehouses/snowflake Connect your Snowflake account to Sidecar ## Prerequisites To follow the steps in this guide, you'll need: * **Account Admin permissions in Sidecar** * **Permissions in Snowflake** that allow you to: * Create database users, create warehouses, create databases, and grant permissions * Set up key-pair authentication ## 1. (Optional) Create a warehouse for Sidecar You can also grant Sidecar an existing warehouse if you prefer. ```sql theme={null} create warehouse if not exists SIDECAR_WH warehouse_size = xsmall warehouse_type = standard auto_suspend = 60 auto_resume = true initially_suspended = true comment = 'Used by Sidecar Data'; ``` ## 2. Create a user, role, and database for Sidecar ```sql theme={null} -- Create core Sidecar infra: role, user, database use role ACCOUNTADMIN; create role if not exists SIDECAR_ROLE; create user if not exists SIDECAR_USER; grant role SIDECAR_ROLE to user SIDECAR_USER; alter user SIDECAR_USER set default_role = SIDECAR_ROLE; alter user SIDECAR_USER set type = service; alter user SIDECAR_USER set password = 'strong_password_here'; set default_warehouse = ''; -- existing or SIDECAR_WH -- So that any SYSADMIN user can use the Sidecar tables grant role SIDECAR_ROLE to role SYSADMIN; -- Create database for Sidecar create database if not exists SIDECAR_DATABASE; -- Grant Sidecar role access to Sidecar warehouse grant all on warehouse SIDECAR_DATABASE to role SIDECAR_ROLE; -- Grant Sidecar access to Sidecar database grant all on database SIDECAR_DATABASE to role SIDECAR_ROLE; grant SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES on all tables in database SIDECAR_DATABASE to role SIDECAR_ROLE; grant SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES on future tables in database SIDECAR_DATABASE to role SIDECAR_ROLE; grant SELECT on all views in database SIDECAR_DATABASE to role SIDECAR_ROLE; grant SELECT on future views in database SIDECAR_DATABASE to role SIDECAR_ROLE; grant USAGE, MONITOR on all schemas in database SIDECAR_DATABASE to role SIDECAR_ROLE; grant USAGE, MONITOR on future schemas in database SIDECAR_DATABASE to role SIDECAR_ROLE; ``` ## 3. Add key-pair authentication to the Sidecar user Starting November 2025, Snowflake requires all service users to use key-pair authentication. Sidecar recommends using key-pair when setting up a user for Sidecar. 1. Follow [Snowflake's instructions](https://docs.snowflake.com/en/user-guide/key-pair-auth) for generating a key-pair. 2. Using the public key generated, alter the user for Sidecar: ```sql theme={null} ALTER USER SIDECAR_USER SET RSA_PUBLIC_KEY='public_key_here'; ``` ## 4. Grant Sidecar access to Snowflake system views and warehouse monitoring ```sql theme={null} grant IMPORTED PRIVILEGES on database SNOWFLAKE to role SIDECAR_ROLE; grant CREATE DATABASE on ACCOUNT to role SIDECAR_ROLE; grant MANAGE WAREHOUSES ON ACCOUNT to role SIDECAR_ROLE; ``` ## 5. Grant Sidecar access to databases you'd like to monitor ```sql theme={null} -- Use SHOW DATABASES to get a list of all your databases -- Repeat for all databases you'd like Sidecar to monitor grant usage, monitor on DATABASE TO ROLE SIDECAR_ROLE; grant usage, monitor on all schemas IN DATABASE to role SIDECAR_ROLE; grant usage, monitor on future schemas IN DATABASE to role SIDECAR_ROLE; ``` ## 6. Grant Sidecar access to schemas you'd like to monitor ```sql theme={null} -- Repeat for all databases + schemas you'd like Sidecar to monitor grant select on all tables in schema . to role SIDECAR_ROLE; grant select on future tables in schema . to role SIDECAR_ROLE; grant select on all views in schema . to role SIDECAR_ROLE; grant select on future views in schema . to role SIDECAR_ROLE; ``` This command generates the SQL statements for all `(database.schema)` pairs. You must grant access to databases before running this (Step 5). ```sql theme={null} SELECT 'GRANT SELECT ON ' || k.scope || ' ' || o.obj || ' IN SCHEMA "' || REPLACE(s.catalog_name, '"','""') || '"."' || REPLACE(s.schema_name, '"','""') || '" TO ROLE SIDECAR_ROLE;' AS grant_stmt FROM SNOWFLAKE.ACCOUNT_USAGE.SCHEMATA AS s , LATERAL (SELECT 'ALL' AS scope UNION ALL SELECT 'FUTURE') AS k , LATERAL (SELECT 'TABLES' AS obj UNION ALL SELECT 'VIEWS') AS o WHERE s.deleted IS NULL AND s.catalog_name <> 'SNOWFLAKE' AND NOT STARTSWITH(s.catalog_name, 'USER$') ORDER BY s.catalog_name, s.schema_name, o.obj, k.scope; ``` For customers who only wish to grant database-level privileges, use the following. **Note: Database-level privileges are ignored if schema-level privileges are granted to other users, so this approach may lead to inconsistent access.** ```sql theme={null} SELECT 'GRANT SELECT ON ' || k.scope || ' ' || o.obj || ' IN DATABASE "' || REPLACE(d.database_name, '"','""') || '" TO ROLE SIDECAR_ROLE;' AS grant_stmt FROM SNOWFLAKE.ACCOUNT_USAGE.DATABASES AS d , LATERAL (SELECT 'ALL' AS scope UNION ALL SELECT 'FUTURE') AS k , LATERAL (SELECT 'TABLES' AS obj UNION ALL SELECT 'VIEWS') AS o WHERE d.deleted IS NULL AND d.database_name <> 'SNOWFLAKE' AND NOT STARTSWITH(d.database_name, 'USER$') ORDER BY d.database_name, o.obj, k.scope; ``` ## 7. Locate your Snowflake Account ID 1. In Snowflake, in the bottom-left corner, click your avatar. 2. Select **Account > View Account Details**. 3. Copy the value for **Account Identifier**. ## 8. Connect Snowflake to Sidecar 1. On the **Integrations** page, navigate to the Snowflake integration. 2. Enter your **Account ID** (Step 7). 3. Enter the name of the user you created (e.g., `SIDECAR_USER`) (Step 2). 4. Enter either the password or private key + private key passphrase for the Sidecar user (Step 3). 5. Click **Test Connection**. 6. Click **Save**. ## Add Snowflake MCP to Agent Console After the warehouse connection is saved, follow [Set up Snowflake MCP](/integrations/mcp-servers/snowflake) to give Sidecar agents read-only query access. # Fivetran Source: https://docs.sidecardata.com/integrations/extract-load/fivetran Connect your Fivetran account to Sidecar ## Requirements A Fivetran account on a **Standard**, **Enterprise**, or **Business Critical** plan is required. Sidecar will need an API key from a user with read and write access to the Fivetran API. ## 1. Create a Fivetran API key 1. In the left-hand navigation bar in Fivetran, look for the username at the bottom. 2. Click the dropdown. You will see an **API Key** section. Click the API Key link. 3. Click **Generate new API Key**. 4. Copy the **API Key** and **API Secret** (not the base64 version) and save them in a safe place. ## 2. Connect Fivetran to Sidecar 1. In the Onboarding page (or Settings), navigate to the `Connect your Extract & Load tool` section. 2. Enter the `API Key` and `API Secret` from Step 1. 3. Click `Test` then `Save`. ## 3. Enable the Fivetran Platform connector Enable the Fivetran Platform connector and the Quickstart Transformations for full metadata coverage. # BigQuery MCP Source: https://docs.sidecardata.com/integrations/mcp-servers/bigquery Use Google's managed BigQuery and Cloud Logging MCP servers with Sidecar agents Sidecar connects agents to Google's managed MCP servers natively. When your workspace has a [BigQuery integration](/integrations/data-warehouses/bigquery), two servers appear automatically in **Integrations → MCP Servers**: * **BigQuery** — Google's managed server at `https://bigquery.googleapis.com/mcp` * **Cloud Logging** — Google's managed server at `https://logging.googleapis.com/mcp` Sidecar authenticates to these servers with your existing BigQuery service account. It mints a short-lived Google access token automatically each time an agent session starts. You never enter, rotate, or refresh a token. Google's managed servers use OAuth 2.0 bearer tokens checked against IAM. There is no interactive consent screen for a service account — the IAM permissions on the service account are the authorization. ## Prerequisites * A connected [BigQuery integration](/integrations/data-warehouses/bigquery). The Google MCP servers reuse its service account and custom role, which include every permission the BigQuery MCP server needs. No new APIs need to be enabled: the MCP interface is part of the BigQuery and Cloud Logging APIs, which your integration already uses. No new key or other credential is entered in Sidecar. If you created the Sidecar custom role before `mcp.tools.call` was added to the [BigQuery integration instructions](/integrations/data-warehouses/bigquery), edit the role and add that permission in each project. The Cloud Logging server needs log read access that the custom role does not include. If you use that server, also grant `roles/logging.viewer` to the service account in each project — or `roles/logging.privateLogViewer` to read data-access audit logs. ## Confirm the connection 1. In Sidecar, select **Integrations → MCP Servers**. 2. Find the **BigQuery** and **Cloud Logging** rows. 3. After the IAM grants propagate, the status shows **Connected**. If a server shows **Auth error**, open its status detail: it lists the missing roles and the exact `gcloud` commands to fix them. Sidecar rechecks the connection hourly. Continue by [granting the server to an agent and selecting it for jobs](/products/agent-console/setup/give-agents-mcp-access). ## Available tools The BigQuery server exposes read-oriented tools including `list_dataset_ids`, `list_table_ids`, `get_dataset_info`, `get_table_info`, and `execute_sql_readonly`. The Cloud Logging server exposes read-only tools for searching log entries and listing logs, buckets, and views. See Google's [BigQuery MCP reference](https://docs.cloud.google.com/bigquery/docs/reference/mcp) and [Cloud Logging MCP reference](https://docs.cloud.google.com/logging/docs/reference/v2_mcp/mcp). Queries run as the Sidecar service account, the same identity as the rest of your Sidecar BigQuery integration. ## Alternative: self-hosted BigQuery MCP If you need tools Google's managed server does not provide, you can still host the open source [MCP Toolbox for Databases](https://mcp-toolbox.dev/documentation/connect-to/ides/bigquery_mcp/) behind an HTTPS endpoint that accepts a stable bearer token, and register it through the [custom connector](/integrations/mcp-servers/connect-an-mcp-server). Expose a read-only toolset for Agent Console jobs and do not publish an unauthenticated endpoint. ## Troubleshooting One or more IAM permissions are missing, or a grant has not propagated yet. Open the server's status detail for the exact missing permissions and commands. IAM changes can take a few minutes to take effect. The Sidecar custom role must be granted in every project agents query, not only the service account's home project. Check the project named in the error. Limit the service account's read access with dataset-level access controls that cover only the datasets agents may read. # Connect an MCP server Source: https://docs.sidecardata.com/integrations/mcp-servers/connect-an-mcp-server Register and manage MCP servers that Sidecar agents can use Register an MCP server at the workspace level before granting it to an Agent Console agent. You can connect a custom endpoint or enable MCP for a supported native integration. This workflow connects external MCP servers to Sidecar agents. To connect the Sidecar MCP server to an external AI client, see [Use Sidecar MCP in an AI client](/integrations/other/sidecar-mcp). You must be an Account Admin to manage MCP servers. ## MCP setup guides Give agents dbt Cloud investigation and retry tools. Use Sidecar's native Snowflake MCP setup. Use Google's managed BigQuery and Cloud Logging MCP servers natively. Register a Databricks managed MCP server. Host or bridge a Redshift MCP server for Sidecar. ## Requirements for a custom endpoint Sidecar's custom connector expects the exact MCP endpoint URL to: * Support the MCP Streamable HTTP transport * Be reachable from Sidecar's infrastructure * Accept a static token in the `Authorization: Bearer ` header * Support MCP initialization and `tools/list` * Respond to connection checks within 30 seconds Use HTTPS for every production endpoint. A local `stdio` command, an SSE-only URL, or a server that requires an interactive OAuth flow cannot be registered directly. ## Add a server 1. In Sidecar, select **Integrations**. 2. Open the **MCP Servers** tab. 3. Click **Add MCP**. Add an MCP server dialog with native connector and custom server options Choose a setup method. Select **Custom server**, then enter: * **Display name** — the label people see in Sidecar * **Name** — a stable machine-readable name * **Server URL** — the full Streamable HTTP MCP endpoint * **Bearer token** — the workspace credential Sidecar sends to the server Click **Add server**. Custom MCP server form with example display name, machine name, HTTPS URL, and bearer token Connect [Snowflake](/integrations/data-warehouses/snowflake) first. In **Add MCP**, select **Snowflake** to open its MCP setup. Paste a programmatic access token for a Snowflake service user. Do not use a personal token. Sidecar derives the server URL from the integration. Connect [dbt Cloud](/integrations/transformation/dbt-cloud) first. In **Add MCP**, select **dbt Cloud** to open its MCP setup. Paste an organization-wide dbt Cloud service token. Do not use a personal token. Sidecar derives the server URL from the integration. Follow [dbt Cloud MCP](/integrations/mcp-servers/dbt-cloud) for prerequisites and setup instructions. BigQuery, Databricks, and Redshift appear as coming soon for native MCP setup. You can still register a compatible endpoint as a custom server. Follow the warehouse-specific guides above for supported endpoints and authentication constraints. ## What happens when you save Sidecar stores the token as a write-only workspace credential, probes the endpoint, and requests its tool list. The token is never displayed again. The server row is saved even when the initial probe reports an authentication or reachability warning. Resolve the warning before depending on the server in a job. ## Manage a server Use the server row actions to: * **Check now** — check endpoint reachability without retrieving the stored credential * **Refresh tools** — re-enter the token and request the tool list again * **Replace token** — replace the write-only credential and repeat tool discovery * **Edit** — change a custom server's display name or URL * **Delete** — remove the server from the workspace **Check now** confirms reachability. Because Sidecar cannot read the stored token back, this check does not prove that the credential is valid. Use **Refresh tools** to test with a token. Changing a custom server URL requires you to re-enter its bearer token. URLs derived from Snowflake or dbt Cloud are not editable. Deleting a server removes its agent grants, job selections, and tool-permission exceptions. ## Give an agent access Registration does not grant the server to any agent. Continue with [Give agents MCP access](/products/agent-console/setup/give-agents-mcp-access). # Databricks MCP Source: https://docs.sidecardata.com/integrations/mcp-servers/databricks Connect a Databricks managed MCP server to Sidecar agents Native Databricks MCP setup in Sidecar is coming soon. Databricks managed MCP servers already use Streamable HTTP, so you can register one through Sidecar's custom connector with a service-principal personal access token (PAT). Databricks recommends OAuth for production. Sidecar's custom connector does not yet perform OAuth token refresh, so this guide uses a service-principal PAT. Set a short lifetime that fits your operating process and rotate it before it expires. ## Choose a managed server Databricks publishes these endpoint patterns: | Capability | Endpoint | Access behavior | | ---------------------- | ---------------------------------------------------------------------------------- | ------------------------------------ | | Genie Agent | `https:///api/2.0/mcp/genie/` | Read-only natural-language analytics | | AI Search | `https:///api/2.0/mcp/ai-search///` | Queries one search index | | Databricks SQL | `https:///api/2.0/mcp/sql` | Can read and write | | Unity Catalog function | `https:///api/2.0/mcp/functions///` | Runs a predefined function | See [Databricks managed MCP servers](https://docs.databricks.com/aws/en/agents/mcp/managed-mcp) for current endpoints, release stages, scopes, and resource permissions. Prefer a Genie Agent, AI Search index, or narrowly scoped Unity Catalog function when possible. The Databricks SQL server can modify data, and Sidecar applies MCP approval settings to the server as a whole rather than to individual tools. ## Prepare the Databricks identity 1. Create a Databricks service principal for Sidecar automation. 2. Add it to the workspace. 3. Grant it access to the selected MCP server and its underlying resource. 4. For a SQL-backed resource, grant **Can use** on the SQL warehouse and only the required Unity Catalog privileges. If you also connect Databricks as a Sidecar warehouse integration, follow the [Databricks integration guide](/integrations/data-warehouses/databricks) for the base service principal and Unity Catalog grants. ## Create a service-principal PAT A workspace admin can create a PAT on behalf of the service principal. Replace the application ID and choose a lifetime that matches your rotation policy. This example uses 90 days: ```bash theme={null} databricks token-management create-obo-token \ --comment "Sidecar Agent Console MCP" \ --lifetime-seconds 7776000 ``` Copy the returned token value. See Databricks' [service-principal token management](https://docs.databricks.com/aws/en/admin/users-groups/manage-service-principals#manage-tokens-for-a-service-principal) and [`create-obo-token` CLI reference](https://docs.databricks.com/aws/en/dev-tools/cli/reference/token-management-commands#databricks-token-management-create-obo-token). ## Register the server in Sidecar Register each Databricks endpoint as a separate MCP server. 1. In Sidecar, select **Integrations → MCP Servers**. 2. Click **Add MCP**, then select **Custom server**. 3. Enter values like these for a Genie Agent: | Field | Example | | ---------------- | --------------------------------------------------------------------- | | **Display name** | `Databricks Genie — Finance` | | **Name** | `databricks_genie_finance` | | **Server URL** | `https://dbc-a1b2c3d4.cloud.databricks.com/api/2.0/mcp/genie/01ef...` | | **Bearer token** | The service-principal PAT | 4. Click **Add server**. 5. Confirm that the server status is **Connected** and review the discovered tools. The hostname must be your workspace hostname, not the account-console hostname or a SQL warehouse HTTP path. Databricks documents the bearer header and client setup in [Connect MCPs to AI assistants and coding agents](https://docs.databricks.com/aws/en/agents/mcp/connect-clients#connect-clients-using-personal-access-token-pat-authentication). Custom MCP server form populated with a Databricks managed MCP endpoint Continue by [granting the server to an agent and selecting it for jobs](/products/agent-console/setup/give-agents-mcp-access). ## Operate the connection * Replace the token in Sidecar before the PAT expires. * Use one service principal per security boundary when different agents need different access. * Add Sidecar's outbound addresses to Databricks workspace IP access lists when your workspace restricts clients. * Test the exact endpoint and PAT with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) when tool discovery fails. Databricks-hosted custom MCP servers do not support PAT authentication. The direct PAT setup above applies to Databricks managed MCP servers and MCP Services. Put a compatible bearer-authenticated gateway in front of a custom Databricks-hosted server before registering it in Sidecar. # dbt Cloud MCP Source: https://docs.sidecardata.com/integrations/mcp-servers/dbt-cloud Give Sidecar agents access to dbt Cloud investigation and retry tools Enable dbt Cloud MCP so Agent Console agents can inspect jobs, run errors, artifacts, lineage, and model health and performance. Agents can also retry an existing job run. ## Before you start You need: * Account Admin permissions in Sidecar * A connected [dbt Cloud integration](/integrations/transformation/dbt-cloud) * An **Access URL** saved on the integration's **Connection** tab, including for accounts that use standard URLs * A production deployment environment accessible to the integration credential * A dbt Cloud service account token with access to the projects and operations your agents need The MCP token is shared by agent runs that have access to this server. Use an organization-wide service account token. ## Enable dbt Cloud MCP in Sidecar 1. In Sidecar, open **Integrations → dbt Cloud**. 2. On the **Connection** tab, confirm that your connection and **Access URL** are saved. 3. Open the **MCP** tab. 4. Click **Enable MCP**. 5. Paste your token into **Service token (organization-wide)**. 6. Click **Add server**. 7. In **Integrations → MCP Servers**, confirm that the server is connected. You can also open this setup from **Integrations → MCP Servers → Add MCP → dbt Cloud**. Sidecar configures the endpoint and production environment automatically, then connects to the server and discovers its tools. You do not need to enter an MCP URL or configure custom headers. The token is stored as a write-only credential and is never displayed again. Sidecar currently selects the first production environment it finds while checking the account's projects. It does not automatically switch to the environment of each failing run. Keep this limitation in mind if your account has multiple production environments. ## Finish agent setup Registering the server does not give it to an agent automatically. [Grant the dbt Cloud MCP server to an agent and select it for jobs](/products/agent-console/setup/give-agents-mcp-access). For native dbt Firefighter jobs, grant the server to the **Reliability** agent. Sidecar adds the matching dbt Cloud server to the job's connections when it is available. This optional connection works alongside the job's warehouse connection. The server includes `retry_job_run`, which executes work in dbt Cloud. Configure [MCP approval settings](/products/agent-console/setup/give-agents-mcp-access#configure-approvals-for-an-mcp-server) if these actions require review. The connection exposes investigation tools and retries. It does not expose `trigger_job_run`, `cancel_job_run`, `execute_sql`, or Semantic Layer tools. To let an agent inspect or change dbt source code, also [connect the repository](/products/agent-console/setup/connect-repositories). To rotate credentials or refresh tools, use the row actions in **Integrations → MCP Servers**. See [Manage a server](/integrations/mcp-servers/connect-an-mcp-server#manage-a-server). ## Troubleshooting Save the dbt Cloud integration first. Confirm that **Access URL** is populated on the **Connection** tab, even if your account uses a standard dbt Cloud URL. Confirm that the account has a production deployment environment and that the integration credential can access its projects and environments. Then save the MCP credential again. In **Integrations → MCP Servers**, select **Replace token** for the dbt Cloud server and save its service token again. Sidecar must resolve the production environment again before the connection can be used. Confirm that the server is connected, granted to the agent, and enabled for the job. For native dbt Firefighter jobs, the server must belong to the dbt Cloud integration used by the job. # Redshift MCP Source: https://docs.sidecardata.com/integrations/mcp-servers/redshift Connect a hosted Amazon Redshift MCP server to Sidecar agents Native Redshift MCP setup in Sidecar is coming soon. Today, you can register a remote Redshift MCP endpoint through Sidecar's custom connector. AWS Labs publishes an [Amazon Redshift MCP Server](https://awslabs.github.io/mcp/servers/redshift-mcp-server) that discovers provisioned clusters and serverless workgroups, explores metadata, and runs single-statement read-only queries. ## Plan the deployment The AWS Labs setup starts the server as a local `stdio` process. Sidecar cannot run that command. To use it with Agent Console, deploy it behind a service or bridge that provides: * An HTTPS MCP Streamable HTTP endpoint * A stable bearer token for Sidecar * Access to AWS through an IAM role or another AWS credential-provider-chain method * Network access to the Redshift Data API and any required private resources The finished URL should look like `https://redshift-mcp.example.com/mcp`. It must meet Sidecar's [custom endpoint requirements](/integrations/mcp-servers/connect-an-mcp-server#requirements-for-a-custom-endpoint). Do not expose the local AWS Labs server directly to the internet and do not place long-lived AWS access keys in Sidecar's **Bearer token** field. That field authenticates Sidecar to your MCP gateway, not the gateway to AWS. ## Configure AWS access Attach a dedicated IAM role to the hosted MCP workload. The AWS Labs server documents these permissions as its starting point: ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "redshift:DescribeClusters", "redshift-serverless:ListWorkgroups", "redshift-serverless:GetWorkgroup", "redshift-data:ExecuteStatement", "redshift-data:DescribeStatement", "redshift-data:GetStatementResult", "redshift-serverless:GetCredentials", "redshift:GetClusterCredentialsWithIAM", "redshift:GetClusterCredentials" ], "Resource": "*" } ] } ``` Scope the resources and conditions more narrowly for your environment where the AWS actions support it. In the workload, set the region explicitly—for example, `AWS_REGION=us-east-1`. Prefer an attached IAM role over static `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` values. ## Configure database access IAM permission to call the Redshift Data API does not grant access to data. Create a least-privilege database identity with `USAGE` on allowed schemas and `SELECT` on allowed tables and views. The [Redshift warehouse integration guide](/integrations/data-warehouses/redshift) includes SQL for a read-only `sidecar_user`, schema grants, future-table grants, and a grant-statement generator. Reuse it only when the MCP server should have the same access as Sidecar's metadata integration. Avoid granting `CREATEUSER` solely for the AWS Labs `review_cluster` tool. The AWS Labs guide notes that this tool needs elevated system-view access. Omit or filter it at your hosted MCP layer when agents only need metadata discovery and read-only queries. If you cannot filter it, leave the elevated privileges ungranted so the tool cannot perform the review. ## Validate the server before hosting Use the official local configuration to confirm AWS and Redshift permissions before adding the HTTP bridge: ```json theme={null} { "mcpServers": { "awslabs.redshift-mcp-server": { "command": "uvx", "args": ["awslabs.redshift-mcp-server@latest"], "env": { "AWS_PROFILE": "sidecar-redshift-mcp", "AWS_REGION": "us-east-1", "FASTMCP_LOG_LEVEL": "INFO" } } } } ``` This configuration is for local validation only. The value you register in Sidecar must be the hosted Streamable HTTP URL, not this command. ## Register the hosted endpoint 1. In Sidecar, select **Integrations → MCP Servers**. 2. Click **Add MCP**, then select **Custom server**. 3. Enter values like these: | Field | Example | | ---------------- | --------------------------------------------- | | **Display name** | `Redshift — Analytics` | | **Name** | `redshift_analytics` | | **Server URL** | `https://redshift-mcp.example.com/mcp` | | **Bearer token** | The stable token accepted by your MCP gateway | 4. Click **Add server**. 5. Confirm that the server status is **Connected** and review the discovered tools. Continue by [granting the server to an agent and selecting it for jobs](/products/agent-console/setup/give-agents-mcp-access). ## Troubleshooting Confirm that you registered the public or privately routable HTTPS `/mcp` endpoint. A local `uvx` command or `localhost` URL is not reachable from Sidecar. Check the gateway's TLS certificate, firewall, and request timeout. Check the workload's AWS region and IAM permissions for provisioned Redshift and Redshift Serverless discovery. Confirm that the attached IAM role is the identity the server is actually using. Check the Data API credential actions and the Redshift database user's `USAGE` and `SELECT` grants. Cluster discovery and database query access use separate permissions. # Snowflake MCP Source: https://docs.sidecardata.com/integrations/mcp-servers/snowflake Give Sidecar agents read-only query access through a Snowflake-managed MCP server Sidecar provides native setup for Snowflake MCP. The Agent Console reuses the Snowflake-managed MCP server created for Ask Sidecar, but it authenticates with an organization-wide service-user token. A personal PAT on the **Ask Sidecar** tab applies only to that person. The PAT on the **MCP** tab is shared by Agent Console jobs. Use a service user for the Agent Console credential. ## Before you start You need: * Account Admin permissions in Sidecar * A connected [Snowflake integration](/integrations/data-warehouses/snowflake) * A verified Snowflake MCP server, following the admin steps in [Ask Sidecar with Snowflake query execution](/products/agents/ask-sidecar-snowflake#admin-setup) * A Snowflake service user whose role can query only the warehouses, databases, and schemas agents need The Sidecar setup creates `SIDECARMCPSERVER` in the `PUBLIC` schema of your selected Sidecar database. It exposes one `executesql` tool with Snowflake's `read_only` option enabled. See Snowflake's [CREATE MCP SERVER reference](https://docs.snowflake.com/en/sql-reference/sql/create-mcp-server) for the underlying object and tool specification. ## Configure network access Snowflake requires service users who authenticate with Programmatic Access Tokens to be subject to a network policy with at least one network rule by default. Sidecar sends Snowflake MCP requests from this production outbound IP address: ```text theme={null} 44.236.246.98/32 ``` Check whether a user-level or account-level network policy applies to the service user. A user-level policy overrides an account-level policy. ```sql theme={null} SHOW PARAMETERS LIKE 'NETWORK_POLICY' FOR USER SIDECAR_USER; SHOW PARAMETERS LIKE 'NETWORK_POLICY' IN ACCOUNT; ``` If a policy applies, inspect whether it uses network rules or the legacy IP allowlist: ```sql theme={null} DESCRIBE NETWORK POLICY ; ``` For a rule-based or new policy, create a network rule for Sidecar in the database that contains `SIDECARMCPSERVER`: ```sql theme={null} USE ROLE ACCOUNTADMIN; CREATE NETWORK RULE .PUBLIC.SIDECAR_MCP_INGRESS MODE = INGRESS TYPE = IPV4 VALUE_LIST = ('44.236.246.98/32') COMMENT = 'Sidecar production outbound IP for Snowflake MCP'; ``` If you created `SIDECAR_MCP_INGRESS` during Ask Sidecar setup, reuse it and skip the `CREATE NETWORK RULE` statement. Add the rule to an existing rule-based policy without replacing its other rules: ```sql theme={null} ALTER NETWORK POLICY ADD ALLOWED_NETWORK_RULE_LIST = ('.PUBLIC.SIDECAR_MCP_INGRESS'); ``` If `DESCRIBE NETWORK POLICY` shows `ALLOWED_IP_LIST` instead of `ALLOWED_NETWORK_RULE_LIST`, do not add the Sidecar rule to that legacy policy. Snowflake requires network rules for PAT access and recommends against mixing legacy IP lists with network rules. Create a rule-based user policy that reproduces every restriction the service user needs, then add the Sidecar rule and attach the new policy. If no rule-based policy applies, create a dedicated policy and attach it to the service user: ```sql theme={null} CREATE NETWORK POLICY SIDECAR_AGENT_CONSOLE_NETWORK_POLICY ALLOWED_NETWORK_RULE_LIST = ('.PUBLIC.SIDECAR_MCP_INGRESS'); ALTER USER SIDECAR_USER SET NETWORK_POLICY = SIDECAR_AGENT_CONSOLE_NETWORK_POLICY; ``` If you use a different service user, replace `SIDECAR_USER` with its name. See Snowflake's [programmatic access token guide](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens#network-policy-requirements) and [network policy guidance](https://docs.snowflake.com/en/user-guide/network-policies). ## Create the organization PAT You can reuse the `SIDECAR_USER` service user from the [Snowflake integration setup](/integrations/data-warehouses/snowflake#2-create-a-user-role-and-database-for-sidecar), or create a separate service user with narrower data access. The following example creates a 90-day PAT for the existing Sidecar service user and restricts it to `SIDECAR_ROLE`: ```sql theme={null} ALTER USER IF EXISTS SIDECAR_USER ADD PROGRAMMATIC ACCESS TOKEN SIDECAR_AGENT_CONSOLE ROLE_RESTRICTION = 'SIDECAR_ROLE' DAYS_TO_EXPIRY = 90 COMMENT = 'Sidecar Agent Console warehouse access'; ``` Copy the `token_secret` value from the result. Snowflake shows it only once. Change the expiration to comply with your authentication policy. Snowflake requires a role restriction for service-user PATs by default. Your authentication policies must also allow `PROGRAMMATIC_ACCESS_TOKEN` as an authentication method. See Snowflake's [programmatic access token guide](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens) for authentication policy requirements, token generation, and rotation. ## Enable Snowflake MCP in Sidecar 1. In Sidecar, select **Integrations**. 2. Open **Snowflake**, then select the **MCP** tab. 3. Click **Enable MCP**. 4. Paste the service user's PAT into **Service account PAT (organization-wide)**. 5. Click **Add server**. Sidecar derives the endpoint from the Snowflake account identifier and the database selected during MCP server setup. It then connects to the server and discovers its tools. ## Finish agent setup Registering the server does not give it to an agent automatically. [Grant the Snowflake MCP server to an agent and select it for jobs](/products/agent-console/setup/give-agents-mcp-access). Rotate the PAT before it expires. In **Integrations → MCP Servers**, open the Snowflake row and select **Replace token**. ## Troubleshooting Complete the [Snowflake MCP admin setup](/products/agents/ask-sidecar-snowflake#admin-setup) on the **Ask Sidecar** tab. Run the generated SQL, then click **Verify MCP Server** before returning to the **MCP** tab. Confirm that the token belongs to a service user, its role restriction names a role granted to that user, and the token has not expired. Confirm that the effective network policy allows `44.236.246.98/32` and that the authentication policy permits `PROGRAMMATIC_ACCESS_TOKEN`. The PAT's restricted role controls data access. Grant that role `USAGE` on the required warehouse, database, and schemas, plus `SELECT` on the required tables and views. Do not grant broader access than the agents need. # Use Sidecar MCP in an AI client Source: https://docs.sidecardata.com/integrations/other/sidecar-mcp Connect the Sidecar MCP server to an external agent harness or AI IDE The Sidecar MCP server gives AI agents live access to your data catalog: dbt models, warehouse tables, dashboards, column-level lineage, and your team's knowledge base. Ask "what feeds the revenue dashboard?" or "what breaks if I change this column?" and the agent answers from the same cross-tool context Sidecar has. This is not the Agent Console MCP setup. To give Sidecar agents access to an external MCP server, see [Connect an MCP server](/integrations/mcp-servers/connect-an-mcp-server). **Server URL:** `https://service-mcp.sidecardata.com/sidecar/mcp` ## Connect with OAuth (recommended) No token needed — you'll be prompted to log in with your Sidecar account in the browser. Run the following command in your terminal: ```bash theme={null} claude mcp add --transport http sidecar-mcp https://service-mcp.sidecardata.com/sidecar/mcp ``` Then run `/mcp` inside a Claude Code session and follow the login prompt. 1. In [claude.ai](https://claude.ai), go to **Settings → Connectors**. 2. Click **Add custom connector**. 3. Paste `https://service-mcp.sidecardata.com/sidecar/mcp` and click **Add**. 4. Click **Connect** and log in with your Sidecar account. 1. Open **Cursor Settings → MCP** and add a new server with URL `https://service-mcp.sidecardata.com/sidecar/mcp`. 2. Cursor detects OAuth support — click **Login** and approve access in the browser. Run the following command in your terminal: ```bash theme={null} code --add-mcp '{"name":"sidecar-mcp","type":"http","url":"https://service-mcp.sidecardata.com/sidecar/mcp"}' ``` Start the server from the **Extensions** view or when prompted in chat; VS Code walks you through the OAuth login. ## Connect with a token Use a token for clients without OAuth support, service accounts, or CI. ### 1. Create a token 1. In the Sidecar app, navigate to the **Users** tab. 2. Click the **Tokens** tab. 3. Click **Create Token**. 4. Enter a name for the token. 5. Set the expiration (1–365 days, or leave empty for no expiration). 6. Click **Create**. The token is only visible once. Copy it and store it in a safe place. ### 2. Configure your client Add the following to `~/.codex/config.toml`. The Codex CLI and IDE extension share this file: ```toml theme={null} [mcp_servers.sidecar] url = "https://service-mcp.sidecardata.com/sidecar/mcp" bearer_token_env_var = "SIDECAR_MCP_TOKEN" ``` Then set `SIDECAR_MCP_TOKEN` in your shell environment to the token you created in Step 1. Run the following command in your terminal: ```bash theme={null} claude mcp add --transport http sidecar-mcp https://service-mcp.sidecardata.com/sidecar/mcp \ --header "Authorization: Bearer scp_mcp_rest_of_generated_token" ``` Replace `scp_mcp_rest_of_generated_token` with the token you created in Step 1. Use the following details to manually configure the MCP server in your IDE: | Field | Value | | ----------------- | ------------------------------------------------- | | **URL** | `https://service-mcp.sidecardata.com/sidecar/mcp` | | **Authorization** | `Bearer scp_mcp_rest_of_generated_token` | Replace `scp_mcp_rest_of_generated_token` with the token you created in Step 1. ## Teach your agent when to use Sidecar Connecting the server makes Sidecar's tools available, but your agent might not use them unless you tell it when they matter. Add the following block to the `CLAUDE.md` or `AGENTS.md` file in your data project. In a monorepo, add it to the instruction file closest to your dbt or analytics code. ```markdown theme={null} ## Use Sidecar for data context Use the connected Sidecar MCP proactively whenever a task involves warehouse data, dbt models or sources, BI assets, lineage, or business definitions. - When a table, model, source, column, dashboard, metric, or business concept is named, resolve or search for it in Sidecar. Ground your answer in catalog metadata instead of guessing identifiers, schemas, owners, or definitions. - Before planning a refactor or changing warehouse SQL, a dbt model, a source definition, or a schema contract, inspect the relevant upstream and downstream lineage. Inspect column-level lineage when a column changes. - After making one of those changes, calculate downstream impact. Report the affected models, tables, dashboards, and other consumers before declaring the work complete. - For open-ended discovery, start with the catalog overview, then search and fetch detailed asset context as needed. Use linked tests, tickets, team discussions, knowledge-base content, and Context Garage content when relevant to explain business intent. - If Sidecar returns multiple matches, disambiguate them using their identifiers and source systems. Do not silently choose a similarly named asset. - Treat Sidecar as the source of truth for cataloged metadata and cross-tool lineage. Treat repository files as the source of truth for unsynced local code, and call out when the two might differ. Sidecar is read-only; use other authorized tools for live data queries or changes. - Summarize the Sidecar evidence that informed the work, including the resolved asset identifiers and any important downstream impact. If Sidecar is unavailable or finds no match, say so and continue with the best local evidence. ``` If your AI client supports reusable skills or rules, you can use the same text there instead. Scope it to data and dbt work so Sidecar is invoked when its catalog context is useful. ## What you can ask Once connected, try prompts like: * *"What data do we have about customers?"* * *"What feeds the revenue dashboard, and when did its sources last refresh?"* * *"If I change `orders.customer_id`, what breaks downstream?"* ## Available tools | Tool | What it does | | --------------------------------------------------------------- | ---------------------------------------------------------------------------- | | `get_catalog_overview` | Summary of the catalog: connected tools, asset counts, tags, company context | | `resolve_asset_id` | Look up an asset by name — schema, columns, description | | `advanced_search` | Find assets by identifier, keyword, or semantic similarity | | `describe_asset` | Deep-dive on one asset: overview, columns, tests, tickets, Slack context | | `inspect_lineage_details` | Upstream and downstream lineage graph for an asset | | `calculate_downstream_impact` | Blast-radius analysis for a change | | `get_column_lineage` | Column-level lineage for a specific column | | `get_context_repo` | The semantic contract deployed to this token's Context Garage | | `list_knowledge_base_files` / `get_knowledge_base_file_content` | Browse and read your team's knowledge base | | `load_skill` | Load a Sidecar development guide into the agent's context | All tools are read-only — the server never modifies your catalog or warehouse. ## Troubleshooting * **401 / authentication errors** — your token expired or the OAuth session lapsed. Re-run the login (OAuth) or create a fresh token. * **Search returns nothing** — call `get_catalog_overview` first to see what's actually in the catalog for your account; your user may not have access to the workspace you expect. * **OAuth login never opens or loops** — confirm the URL is exactly `https://service-mcp.sidecardata.com/sidecar/mcp` and that your client is up to date. Codex does not currently support OAuth with Sidecar — use a token instead. * Still stuck? Contact [support@sidecardata.com](mailto:support@sidecardata.com). Sidecar is also listed in the official [MCP Registry](https://registry.modelcontextprotocol.io) as `com.sidecardata/sidecar`. Clients that browse the registry can install it from there. # Jira Source: https://docs.sidecardata.com/integrations/project-management/jira Connect your Jira Cloud account to Sidecar ## Requirements * Jira Cloud account for your organization * A Sidecar service account/user in Jira * A scoped API token ## 1. Create a Jira user for Sidecar Go to your Jira Project Access settings and add a user for the Sidecar service account: ``` https://my-site-name.atlassian.net/jira/software/projects/PROJECT_KEY/settings/access ``` ## 2. Create a scoped API token 1. Navigate to [API token management](https://id.atlassian.com/manage-profile/security/api-tokens). 2. Create a scoped token with the following scopes: * `read:jira-work` * `write:jira-work` ## 3. Get your Jira Cloud ID Visit the following URL to get your Jira Cloud ID: ``` https://my-site-name.atlassian.net/_edge/tenant_info ``` ## 4. Determine the Jira project key Identify the project key for the Jira project where Sidecar will create issues from ad-hoc requests: ``` https://my-site-name.atlassian.net/jira/software/projects/PROJECT_KEY/ ``` ## 5. Determine the JQL statement for initial issue import Create a [JQL statement](https://support.atlassian.com/jira-software-cloud/docs/use-advanced-search-with-jira-query-language-jql/) to define which existing issues Sidecar should import. ## 6. Connect Jira to Sidecar 1. Go to the **Integrations** page in Sidecar. 2. Find and click on the **Jira** integration under "Browse integrations". 3. Enter your Cloud ID, API token, project key, and JQL statement. 4. Click **Test** then **Save**. A valid JQL statement that retrieves at least one issue is required for a successful connection test. ## Using the Jira Integration Once integrated, Sidecar imports your team's issues and includes business context from Jira in your metadata store. The primary interaction is through the **Sidecar Slackbot**. Tag Sidecar in any Slack thread to automatically summarize the conversation and create a Jira issue: * `@sidecar create ticket` * `@sidecar write ticket` * `@sidecar update ticket` * `@sidecar ticket` All commands do the same thing: 1. Summarize the current state of the thread 2. Update Sidecar's internal records 3. Push the summary to Jira (creating or updating the issue) 4. Add a comment linking back to the original Slack thread You must add the Sidecar Slackbot to any channels where you want it to listen for invocations. # Linear Source: https://docs.sidecardata.com/integrations/project-management/linear Connect your Linear workspace to Sidecar ## Requirements * A Linear instance with at least one active team and project * A Linear Team ID for issue creation (this is where the Slackbot will create issues) ## 1. Connect Linear to Sidecar 1. Go to the **Integrations** page in Sidecar. 2. Find and click on the **Linear** integration under "Browse Integrations". 3. Follow the OAuth flow to connect your Linear account. ## 2. Reinstall the Sidecar Slack app The Sidecar bot needs new permission scopes to respond to tags and read/summarize messages in your Slack threads. A fresh installation of the Sidecar Slack app is required. You can reinstall from the **Slack** page in **Integrations**. ## 3. Provide your Linear Team ID At this time, you'll need to share your Team ID with the Sidecar team directly. We'll add a self-service flow in the future. To find your Linear Team ID: 1. Use `Cmd + K` in Linear to open the Command Menu. 2. Type `UUID` and select **Dev: Copy model UUID**. 3. The UUIDs displayed are contextual — make sure you're on a page relevant to the team you want. 4. Copy the Team UUID. 5. Share this UUID with the Sidecar team in your `#ext-customer-{COMPANY_NAME}` Slack channel. ## Using the Linear Integration Once integrated, Sidecar imports your team's issues and includes business context from Linear in your metadata store. The primary interaction is through the **Sidecar Slackbot**. Tag Sidecar in any Slack thread to automatically summarize the conversation and create a Linear issue: * `@sidecar create ticket` * `@sidecar write ticket` * `@sidecar update ticket` * `@sidecar ticket` All commands do the same thing: 1. Summarize the current state of the thread 2. Update Sidecar's internal records 3. Push the summary to Linear (creating or updating the issue) 4. Add a comment linking back to the original Slack thread You must add the Sidecar Slackbot to any channels where you want it to listen for invocations. # GitHub Source: https://docs.sidecardata.com/integrations/source-control/github Connect GitHub repositories to Sidecar with the Sidecar Data GitHub app Connect GitHub to let Sidecar read selected repositories and deliver Agent Console branches and pull requests. ## Before you start You need an Account Admin role in Sidecar and permission to install or request a GitHub app for the target organization. ## Connect GitHub In Sidecar, select **Integrations**, then open **GitHub**. Click **Link Sidecar Data**. Sidecar sends you to GitHub. Select the GitHub organization and grant access to the repositories Sidecar should use. If the organization requires approval, request the installation from a GitHub organization administrator. Complete the GitHub flow. Sidecar records the installation and displays the connected account. ## Change repository access Return to **Integrations → GitHub** and click **Configure integration in GitHub**. Update the repository selection in GitHub. Uninstalling the app or removing a repository can make existing jobs unready. ## Verify Agent Console access Open an agent's **Settings** page and check **Scope → Repositories**. See [Connect repositories](/products/agent-console/setup/connect-repositories) for job-scope behavior. ## Custodian access Custodian uses an additional GitHub app installation for upstream subscriptions. The **Custodian** section on the GitHub integration page shows its installations and repository access. Follow the [Custodian downstream-impact review recipe](/products/agent-console/recipes/custodian-downstream-impact-review) before binding upstream repositories. Connected GitHub integration with Sidecar Data account and Custodian installation status # GitLab Source: https://docs.sidecardata.com/integrations/source-control/gitlab Connect GitLab repositories to Sidecar through OAuth Connect GitLab to let Sidecar read accessible repositories and deliver Agent Console branches and merge requests. ## Before you start You need an Account Admin role in Sidecar and a GitLab account with access to the target repositories. Sidecar supports `gitlab.com`. Self-managed GitLab instances are not supported by this integration. ## Connect GitLab In Sidecar, select **Integrations**, then open **GitLab**. Disconnected GitLab integration with Connect GitLab with OAuth button Click **Connect GitLab with OAuth**. Review the requested access in GitLab and authorize Sidecar. Sidecar completes verification and displays the connected GitLab identity. To refresh the authorization later, click **Reconnect GitLab**. ## Verify Agent Console access Open an agent's **Settings** page and check **Scope → Repositories**. See [Connect repositories](/products/agent-console/setup/connect-repositories) for job-scope behavior. # dbt Cloud Source: https://docs.sidecardata.com/integrations/transformation/dbt-cloud Connect your dbt Cloud account to Sidecar ## Requirements Sidecar requires a dbt Cloud service account token to access the dbt Cloud API. This token must have permission to access the Administrative API, the Discovery API, and the ability to create and execute jobs. You must be on a **Team** or **Enterprise** plan, and your projects must be on **version 1.0 or later**. ## 1. Create a service account token 1. Navigate to `Account settings` in dbt Cloud. 2. Navigate to `API tokens > Service tokens`. 3. Click `+ Create service token`. 4. Give the service token a name like `sidecar-data`. 5. Click `+ Add permission`. 1) `Job Admin` — to create and execute jobs 2) `Member` — to access the Discovery API and Administrative API 3) `Billing Admin` — to monitor costs 1. `Developer` — to access the Discovery API, create and execute jobs 2. `Account viewer` — to access the Administrative API 3. `Billing Admin` — to monitor costs 6. Click `Save` to create the service token. 7. Copy the service token value and save it in a safe place. ## 2. Connect dbt Cloud to Sidecar 1. In the Onboarding page (or Settings), navigate to the **Connect your dbt Cloud** section. 2. Enter your `Account ID`. This can be found in dbt Cloud under `Account Settings > Account > Account ID`. 3. Paste the `API Token` you created in Step 1. 4. dbt Cloud has standard and non-standard API URLs. Check which type you have by navigating to `Account Settings > Account` in dbt Cloud: * If you see a section called `Access URLs`, you have **non-standard URLs**. * If you do not, you have **standard URLs**. 5. If you have non-standard URLs, enter the values for `Access URL`, `Semantic Layer GraphQL API URL`, and `Discovery API URL`. Otherwise, skip this step. 6. Click `Test` then `Save`. For customers with single-tenant instances of dbt Cloud, the API URLs follow this pattern: * **Access URL:** Your vanity URL for this account * **Discovery API URL:** `https://metadata.YOUR_ACCESS_URL/graphql` * **Semantic Layer GraphQL API URL:** `https://semantic-layer.ABC123.getdbt.com/api/graphql` ## Enable MCP for agents To give Agent Console agents live dbt Cloud investigation and retry tools, follow [dbt Cloud MCP](/integrations/mcp-servers/dbt-cloud). MCP setup requires an **Access URL** saved on the **Connection** tab, even for accounts that use standard URLs. Connecting the integration alone does not enable MCP or grant it to an agent. # dbt Core Source: https://docs.sidecardata.com/integrations/transformation/dbt-core Connect your dbt Core project to Sidecar ## How the integration works dbt Core writes execution artifacts to its `target` directory. Send those artifacts to Sidecar after each production dbt command that you want Sidecar to monitor. You do not need to change how you invoke dbt. Add the Sidecar webhook to the production workflow that already runs your dbt commands. Configure the webhook only in the environments and workflows that you want Sidecar to monitor. For example, add it to your production Airflow DAG without adding it to development DAGs. ### Artifacts to send | dbt command | Required result artifact | Current project artifact to include | Failures captured | | ------------------------------------- | ------------------------ | ----------------------------------- | ----------------------------------------------------- | | `dbt build`, `dbt run`, or `dbt test` | `run_results.json` | `manifest.json` | Model and data test failures | | `dbt source freshness` | `sources.json` | `manifest.json` | Source freshness warnings, errors, and runtime errors | dbt overwrites artifacts in the `target` directory when another dbt command runs. Upload the artifacts immediately after each command that you want to monitor. The result artifact contains the dbt invocation ID and command, so these do not need to be separate webhook fields. Sidecar also does not require the dbt exit code, target name, Git commit SHA, or orchestrator run ID. Your workflow only needs to preserve the dbt exit code so that the original task still reports failure. Include the current `manifest.json` whenever dbt produces it. Sidecar stores the newest manifest as the authoritative project graph for Catalog Sync, and it identifies the adapter and warehouse for Firefighter. Run results are additive execution history and do not have to be paired with a manifest from the same invocation. If dbt exits before writing a manifest, Sidecar can still use the result artifact for Firefighter and can apply it to the newest manifest already stored. If Sidecar has never received a manifest for the project, Catalog Sync waits for one before building the dbt asset inventory. ## Before you begin You need: * A dbt Core project that can run in the environment you want to monitor * Network access from that environment to `https://service-platform.sidecardata.com` * A Sidecar artifact token In Sidecar, open the **dbt Core** connection and click **Generate** to create an artifact token. Store the token in your orchestrator or CI/CD secret manager as `SIDECAR_ARTIFACT_TOKEN`. ## Upload artifacts with the webhook Choose the result type produced by your dbt command. Send `manifest.json` and `run_results.json`: ```bash theme={null} curl --fail-with-body --silent --show-error \ --request POST \ 'https://service-platform.sidecardata.com/api/v1/setup/dbt-core/upload-artifacts/' \ --header "X-Artifact-Token: ${SIDECAR_ARTIFACT_TOKEN}" \ --form 'manifest=@target/manifest.json' \ --form 'run_results=@target/run_results.json' ``` Send `manifest.json` and `sources.json`: ```bash theme={null} curl --fail-with-body --silent --show-error \ --request POST \ 'https://service-platform.sidecardata.com/api/v1/setup/dbt-core/upload-artifacts/' \ --header "X-Artifact-Token: ${SIDECAR_ARTIFACT_TOKEN}" \ --form 'manifest=@target/manifest.json' \ --form 'sources=@target/sources.json' ``` The copy-paste patterns send the current manifest so Firefighter has full warehouse context and Catalog Sync receives the latest project graph. No additional webhook metadata is required. The webhook must run even when dbt exits with an error. Use the pattern for your orchestrator below. ## Configure your workflow Choose the environment that runs your production dbt commands. Capture the dbt exit code locally, upload the artifacts, and then return the original dbt failure. The exit code controls the workflow status and is not sent to Sidecar. If dbt succeeds but the upload fails, return the upload failure. ### Model runs and data tests ```bash theme={null} #!/usr/bin/env bash set -uo pipefail dbt_status=0 dbt build || dbt_status=$? upload_status=0 curl --fail-with-body --silent --show-error \ --request POST \ 'https://service-platform.sidecardata.com/api/v1/setup/dbt-core/upload-artifacts/' \ --header "X-Artifact-Token: ${SIDECAR_ARTIFACT_TOKEN}" \ --form 'manifest=@target/manifest.json' \ --form 'run_results=@target/run_results.json' || upload_status=$? if [ "${dbt_status}" -ne 0 ]; then exit "${dbt_status}" fi exit "${upload_status}" ``` ### Source freshness ```bash theme={null} #!/usr/bin/env bash set -uo pipefail dbt_status=0 dbt source freshness || dbt_status=$? upload_status=0 curl --fail-with-body --silent --show-error \ --request POST \ 'https://service-platform.sidecardata.com/api/v1/setup/dbt-core/upload-artifacts/' \ --header "X-Artifact-Token: ${SIDECAR_ARTIFACT_TOKEN}" \ --form 'manifest=@target/manifest.json' \ --form 'sources=@target/sources.json' || upload_status=$? if [ "${dbt_status}" -ne 0 ]; then exit "${dbt_status}" fi exit "${upload_status}" ``` Create a downstream upload task with the `all_done` trigger rule. Airflow will run the upload after the upstream dbt task succeeds or fails. ```python theme={null} from airflow.operators.bash import BashOperator from airflow.utils.trigger_rule import TriggerRule def sidecar_upload_task(task_id: str, artifact_name: str) -> BashOperator: return BashOperator( task_id=task_id, trigger_rule=TriggerRule.ALL_DONE, append_env=True, env={ "SIDECAR_ARTIFACT_TOKEN": "{{ var.value.sidecar_artifact_token }}", }, bash_command=f""" set -euo pipefail cd /shared/dbt/your-dbt-project curl --fail-with-body --silent --show-error \\ --request POST \\ 'https://service-platform.sidecardata.com/api/v1/setup/dbt-core/upload-artifacts/' \\ --header "X-Artifact-Token: ${{SIDECAR_ARTIFACT_TOKEN}}" \\ --form 'manifest=@target/manifest.json' \\ --form '{artifact_name}=@target/{artifact_name}.json' """, ) upload_run_results = sidecar_upload_task( task_id="upload_dbt_run_results_to_sidecar", artifact_name="run_results", ) main_dbt_task >> upload_run_results upload_freshness = sidecar_upload_task( task_id="upload_dbt_freshness_to_sidecar", artifact_name="sources", ) source_freshness_task >> upload_freshness ``` The dbt task and upload task must use the same `target` directory. Mount a shared or persistent volume when the tasks run on different workers or in different pods. Do not use a downstream upload task for artifacts stored only in an ephemeral dbt container. If parallel dbt tasks share a project, give each task a separate target directory. This prevents one invocation from overwriting another invocation's artifacts before Sidecar receives them. For a Dagster job dedicated to dbt, attach success and failure hooks to the job. The hooks upload the newest result artifact from a shared target directory after each dbt step, including successful freshness checks that contain warnings. ```python theme={null} import os from pathlib import Path import requests from dagster import failure_hook, job, success_hook SIDECAR_UPLOAD_URL = ( "https://service-platform.sidecardata.com/" "api/v1/setup/dbt-core/upload-artifacts/" ) DBT_TARGET_PATH = Path("/shared/dbt/your-dbt-project/target") def upload_dbt_artifacts_to_sidecar(context): manifest_path = DBT_TARGET_PATH / "manifest.json" result_candidates = [ ("run_results", DBT_TARGET_PATH / "run_results.json"), ("sources", DBT_TARGET_PATH / "sources.json"), ] result_name, result_path = max( ((name, path) for name, path in result_candidates if path.exists()), key=lambda candidate: candidate[1].stat().st_mtime, ) with manifest_path.open("rb") as manifest_file, result_path.open("rb") as result_file: response = requests.post( SIDECAR_UPLOAD_URL, headers={ "X-Artifact-Token": os.environ["SIDECAR_ARTIFACT_TOKEN"], }, files={ "manifest": manifest_file, result_name: result_file, }, timeout=30, ) response.raise_for_status() context.log.info("Uploaded dbt invocation to Sidecar") @failure_hook def upload_dbt_artifacts_after_failure(context): upload_dbt_artifacts_to_sidecar(context) @success_hook def upload_dbt_artifacts_after_success(context): upload_dbt_artifacts_to_sidecar(context) @job( hooks={ upload_dbt_artifacts_after_failure, upload_dbt_artifacts_after_success, } ) def production_dbt_job(): # Keep your existing dbt ops and assets here. ... ``` The hooks must be able to read the same target directory as the dbt step. Use this pattern only for jobs whose steps run dbt. If your Dagster run launcher uses ephemeral containers, persist the target directory to a shared volume or call the webhook inside the run container. Add an upload step after the dbt step. The `!cancelled()` condition allows the upload to run after success or failure, while avoiding an upload after the workflow is canceled. ### Model runs and data tests ```yaml theme={null} - name: Run dbt run: dbt build - name: Upload dbt artifacts to Sidecar if: ${{ !cancelled() }} env: SIDECAR_ARTIFACT_TOKEN: ${{ secrets.SIDECAR_ARTIFACT_TOKEN }} run: | curl --fail-with-body --silent --show-error \ --request POST \ 'https://service-platform.sidecardata.com/api/v1/setup/dbt-core/upload-artifacts/' \ --header "X-Artifact-Token: ${SIDECAR_ARTIFACT_TOKEN}" \ --form 'manifest=@target/manifest.json' \ --form 'run_results=@target/run_results.json' ``` ### Source freshness ```yaml theme={null} - name: Check source freshness run: dbt source freshness - name: Upload dbt freshness to Sidecar if: ${{ !cancelled() }} env: SIDECAR_ARTIFACT_TOKEN: ${{ secrets.SIDECAR_ARTIFACT_TOKEN }} run: | curl --fail-with-body --silent --show-error \ --request POST \ 'https://service-platform.sidecardata.com/api/v1/setup/dbt-core/upload-artifacts/' \ --header "X-Artifact-Token: ${SIDECAR_ARTIFACT_TOKEN}" \ --form 'manifest=@target/manifest.json' \ --form 'sources=@target/sources.json' ``` GitHub Actions retains the failed status from the dbt step after running the conditional upload step. Run the webhook in the same container as dbt so it can read the local target directory. The shell returns the dbt failure after attempting the upload. ```yaml theme={null} apiVersion: batch/v1 kind: Job metadata: name: production-dbt spec: template: spec: restartPolicy: Never containers: - name: dbt image: your-dbt-image:latest env: - name: SIDECAR_ARTIFACT_TOKEN valueFrom: secretKeyRef: name: sidecar-dbt key: artifact-token command: ["/bin/bash", "-c"] args: - | set -uo pipefail dbt_status=0 dbt build || dbt_status=$? upload_status=0 curl --fail-with-body --silent --show-error \ --request POST \ 'https://service-platform.sidecardata.com/api/v1/setup/dbt-core/upload-artifacts/' \ --header "X-Artifact-Token: ${SIDECAR_ARTIFACT_TOKEN}" \ --form 'manifest=@target/manifest.json' \ --form 'run_results=@target/run_results.json' || upload_status=$? if [ "${dbt_status}" -ne 0 ]; then exit "${dbt_status}" fi exit "${upload_status}" ``` Use the `sources` form field and `target/sources.json` when the job runs `dbt source freshness`. ## Manual upload You can also upload artifacts while creating or editing a dbt Core connection: 1. Open the **dbt Core** tab on the onboarding or settings page. 2. Upload `manifest.json` and `run_results.json` from a `dbt build`, `dbt run`, or `dbt test` command. 3. Click **Test**, then click **Save**. Manual uploads update Sidecar's dbt metadata. Use automated webhook uploads for Firefighter so Sidecar receives failures when they occur. ## Troubleshooting ### Sidecar did not receive a failed run Confirm that the upload step uses an always-run or failure callback. A command such as `dbt build && curl ...` skips the webhook when dbt fails. ### The artifact file does not exist Confirm that the webhook runs in the same working directory as dbt and uses the configured dbt target path. For ephemeral tasks and pods, upload before the container exits or mount a shared volume. ### Sidecar received the wrong invocation Upload immediately after each dbt command. Do not let another dbt command overwrite the target directory first. Use separate target directories for parallel invocations. # Builder Source: https://docs.sidecardata.com/products/agent-console/agents/builder Use Builder to research, implement, and validate engineering changes Builder turns a scoped engineering request into a reviewable repository change. It can research a codebase, edit files, run validation, and deliver a pull request or branch. ## Use Builder for * Adding or updating dbt models, tests, sources, macros, and documentation * Refactoring a focused area of a data repository * Fixing a well-defined defect * Investigating a repository and returning a text response Builder works best when your instructions name the target, define the outcome, and state what is out of scope. ## Requirements Builder requires repository access. Connect GitHub or GitLab, then select a repository when you [create the job](/products/agent-console/jobs/create-a-job). A warehouse MCP server is optional. Add one when Builder needs to inspect live warehouse evidence. ## Jobs and delivery Builder has no presets. Create a custom job and choose one of these outputs: * **Open a pull request** * **Push to a branch** * **Text response in Agent Console** Builder creates `sidecar/` branches and never merges its work. Follow [Create your first Agent Console job](/products/agent-console/quickstart) for a complete example. Builder page with configured jobs, active controls, and New job button # Choose an agent Source: https://docs.sidecardata.com/products/agent-console/agents/choose-an-agent Compare the live Agent Console agents and choose the right one for your task Choose an agent based on the outcome you need. Each agent has its own instructions, skills, resource requirements, and presets. | Agent | Use it for | Typical output | Important setup | | ----------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------- | | [Builder](/products/agent-console/agents/builder) | Implementing scoped engineering changes | Pull request, branch, or text response | A source-control repository | | [Reliability](/products/agent-console/agents/reliability) | Investigating failures, tests, freshness issues, and incidents | Diagnosis and, when safe, a draft pull request | Repository and warehouse MCP are optional | | [Optimization](/products/agent-console/agents/optimization) | Warehouse cost, query performance, and dbt project health | Evidence-based report or draft pull request | Some workflows require a warehouse MCP | | [Custodian](/products/agent-console/agents/custodian) | Reviewing upstream pull requests for downstream impact | Source-control review and optional downstream remediation | Custodian GitHub access plus an upstream/downstream repository pair | | Concierge | General request routing and guidance | Coming soon | Not yet available | If you send a direct message to the Sidecar Slack app, Sidecar chooses among the available agents. It uses Builder when it cannot classify the request confidently. Agent Console tabs with four available agents and Concierge marked coming soon # Custodian Source: https://docs.sidecardata.com/products/agent-console/agents/custodian Use Custodian to review upstream pull requests for downstream data impact Custodian reviews an upstream GitHub pull request and traces evidence-supported effects into one downstream repository. It can post a structured source-control review and, when configured, prepare a small downstream remediation for human review. Custodian does not use the standard custom-job workflow. You duplicate its immutable **Review changes for downstream impacts** template and configure the copy. ## Requirements You need: * The Custodian GitHub app installed with access to the upstream repository * The upstream repository bound to Custodian * The standard Sidecar GitHub integration connected to the downstream repository * One upstream and one downstream repository that are different The trigger and delivery mode are fixed. The job runs when a pull request changes in the configured upstream repository. It does not have **Run now**. Follow the [Custodian downstream-impact review recipe](/products/agent-console/recipes/custodian-downstream-impact-review) to configure the complete workflow. Custodian downstream-impact review template with Duplicate button Custodian settings with repository access, connected tools, and an empty subscribed repositories section # Optimization Source: https://docs.sidecardata.com/products/agent-console/agents/optimization Use Optimization to review warehouse cost, query performance, and dbt project health Optimization uses available evidence to find cost, performance, and dbt project-health opportunities. It separates direct evidence from inference and does not mutate warehouse data or configuration. ## Use Optimization for * Reviewing expensive query patterns * Prioritizing warehouse optimization opportunities * Summarizing dbt project-health findings * Applying bounded, mechanical dbt fixes for review ## Presets ### Expensive query review This preset reviews the previous 30 days of query history and returns up to ten prioritized query patterns. It requires a warehouse MCP server and does not use repositories. ### dbt project health This preset converts Sidecar's dbt health findings into a prioritized report. When the matching repository is available, it can prepare bounded mechanical fixes in a draft pull request. The job configuration shown in Sidecar is authoritative for the dbt project health trigger. Review it before activating the preset. Use [Connect dbt context](/products/agent-console/setup/connect-dbt) and [Give agents MCP access](/products/agent-console/setup/give-agents-mcp-access) to prepare the required context. Optimization preset dialog with Expensive query review and dbt project health # Reliability Source: https://docs.sidecardata.com/products/agent-console/agents/reliability Use Reliability to diagnose data incidents and make the smallest safe fix Reliability investigates data-platform failures. It diagnoses the symptom and root cause before proposing or making a change. ## Use Reliability for * Broken dbt runs and failing tests * Freshness stalls and volume anomalies * Bad deployments and pipeline failures * Incident reports that separate observed evidence from inference An analysis-only result is valid. Reliability does not change code unless the evidence supports a small, safe fix. ## Resources Repositories and a warehouse MCP server are optional. Connect them when the investigation needs repository history or live warehouse evidence. ## Preset **Investigate custom monitor issues** automatically investigates scheduled custom monitor failures and errors. The preset always preserves the diagnosis and can open a draft pull request when a safe repository fix is relevant. Preset instructions, delivery, resources, and trigger are owned by Sidecar. You can change its active state, MCP selection, tool permissions, and notifications. See [Create a job from a preset](/products/agent-console/jobs/create-a-job#from-a-preset). Reliability preset dialog with Investigate custom monitor issues available to add # Configure a job Source: https://docs.sidecardata.com/products/agent-console/jobs/configure-a-job Manage job instructions, scope, delivery, triggers, MCP access, and tool permissions Open a job from its agent page to review its complete configuration. Custom jobs expose all standard settings. Presets keep product-owned settings read-only. Full Builder job configuration with instructions, scope, trigger, output, MCP servers, and tool permissions ## Active state Use the active toggle in the job header to pause or resume a job. A paused job does not run manually or on its configured trigger. Pausing does not cancel a run already in progress. ## Instructions Instructions define the work performed on every run. You can edit instructions for custom jobs. Preset instructions are read-only. ## Repository scope Custom jobs can use: * **All repositories** — Sidecar resolves every currently accessible repository when each run starts. * A selected subset — the job uses only the saved repositories. If a selected repository loses integration access, the job becomes unready until you restore access or update the scope. Some preset jobs use no repositories or treat them as optional. Their resource contract is read-only. ## Completion and output Custom job options include: * **Open a pull request** * **Push to a branch** * **Text response in Agent Console** Some presets use **Diagnosis and draft pull request**. Custodian uses a fixed source-control review delivery. ## Schedule and trigger Custom jobs support **Manual** and **Scheduled** triggers. For a scheduled job, choose: * **Intervals** — every 1, 2, 3, 4, 6, 8, or 12 hours * **Specific hours** — selected days and hours in an IANA timezone * **Cron expression** — a five-field cron schedule with an explicit timezone Scheduled jobs can still run through **Run now**. Changing a scheduled job to Manual removes its schedule. Preset and template triggers are read-only. They can include monitor events or GitHub pull-request webhooks. Scheduled trigger editor with cron expression and America Los Angeles timezone ## MCP servers The **MCP servers** section lists servers granted to the agent. All granted servers are enabled by default. You can narrow the job to an explicit subset or disable them all. Follow [Give agents MCP access](/products/agent-console/setup/give-agents-mcp-access) for the complete registration, grant, and job-selection model. ## Tool permissions Choose how gateable tools behave: * **Autonomous** — gateable tools run without approval unless listed as exceptions. * **Supervised** — gateable tools pause for Account Admin approval unless listed as exceptions. Exceptions can include web tools and whole MCP servers. Switching modes clears the current exception list after confirmation. Core repository tools always remain available. ## Resource readiness Sidecar checks the resources required by the job. A missing required repository or warehouse MCP blocks the run. Optional resources do not block it. MCP health is informational. A structurally valid warehouse MCP can satisfy readiness even if its latest health check shows a warning; the run still fails if the server cannot be used. ## Notifications Notifications control where job and approval events are delivered. Keep the current configuration unless your Sidecar contact has provided a supported notification route. ## Preset restrictions For a preset job, you can change only: * Active state * MCP server selection * Tool permissions * Notifications Sidecar owns all other fields. Custodian copies use a specialized configuration page. See the [Custodian recipe](/products/agent-console/recipes/custodian-downstream-impact-review). # Create a job Source: https://docs.sidecardata.com/products/agent-console/jobs/create-a-job Create an Agent Console job from scratch, a preset, or a template Open an agent to create a custom job or use one of its released presets. Available options depend on the agent. | Starting point | Use it when | What you can change | | -------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------- | | Custom job | You need your own instructions, scope, output, and manual or scheduled trigger | All standard job settings | | Preset | Sidecar provides a supported recurring or event-driven workflow | Active state, MCP servers, tool permissions, and notifications | | Template | The workflow needs specialized configuration, such as Custodian | Duplicate the read-only template, then configure the copy | ## Create a custom job 1. In Sidecar, select **Agents**. 2. Open the agent that should perform the work. 3. Click **New job**. 4. Complete the form. Empty New job dialog with name, description, instructions, repositories, and delivery fields ### Name and description Use a name that describes a repeatable outcome. The optional description appears in the job list. ### Instructions Describe what the agent should do on every run. State the target, expected result, validation, and important boundaries. ### Repositories Select one or more repositories, or leave the selection empty to use all currently accessible repositories. Learn how the scope changes over time in [Configure a job](/products/agent-console/jobs/configure-a-job#repository-scope). ### Delivery Available options depend on the agent's repository requirements: * **Open a pull request** * **Push to a branch** * **Text response in Agent Console** ### Trigger Choose: * **Manual** — the job runs only when an Account Admin clicks **Run now**. * **Scheduled** — the job runs on an interval, at specific hours, or from a cron expression. **Run now** remains available. Custom jobs cannot select webhook, monitor, or chat triggers. Sidecar owns those trigger types for specialized workflows. Click **Create job** to open its configuration page. MCP servers and tool permissions are not part of the New job dialog. Configure them after Sidecar creates the job. ## From a preset Agents with released presets show **From preset** beside **New job**. 1. Click **From preset**. 2. Review the preset's resources, trigger, and starting state. 3. Add the preset. 4. Open the installed job and review its readiness, MCP selection, tool permissions, and active state. Optimization preset dialog with Expensive query review installed and dbt project health available Sidecar owns the preset's name, description, instructions, repository contract, delivery, and trigger. Updating a released preset can update those product-owned fields. Deleting a preset job does not remove it from the catalog. You can restore it as a fresh job later. ## From a template A template is a read-only definition that never runs directly. 1. Click **From preset**. 2. Click **View template**. 3. Review the fixed workflow. 4. Click **Duplicate**. 5. Configure and activate the new copy. Custodian uses this flow. Follow the [Custodian downstream-impact review recipe](/products/agent-console/recipes/custodian-downstream-impact-review) for its additional GitHub and repository requirements. Immutable Custodian downstream-impact review template with Duplicate button # Runs and approvals Source: https://docs.sidecardata.com/products/agent-console/jobs/runs-and-approvals Follow Agent Console runs, approve gated tools, and review artifacts The **Console** lists runs across every agent and job. A job page also shows its recent runs. Click a run to review its origin, current status, turn timeline, transcript, approvals, and artifacts. Agent Console run list with agent and status filters and scheduled Builder runs ## Run statuses | Status | Meaning | | --------------------- | --------------------------------------------------------------- | | **Queued** | Sidecar accepted the run and is preparing it. | | **Running** | The agent is working. | | **Awaiting input** | The agent needs a reply before it can continue. | | **Awaiting approval** | A gateable tool is waiting for an Account Admin. | | **Blocked** | The run cannot continue without resolving a blocking condition. | | **Succeeded** | The run completed successfully. | | **Partial** | The run completed with an incomplete result or delivery. | | **Failed** | The run stopped with an error. | | **Cancelled** | An Account Admin stopped the run. | ## Start and cancel runs An active manual or scheduled job has **Run now**. Starting it opens the run detail page. Sidecar serializes runs for the same job and target. If the same job is already running, use the existing run instead. Different jobs can run at the same time. Use **Cancel run** to stop an active run. Cancelling closes its pending approvals. ## Transcript Expand a turn to see the agent messages and tool activity for that stage of the run. Older transcripts may become unavailable while run metadata and artifacts remain. Expanded Builder run turn with a Snowflake MCP executesql tool call and agent response ## Approvals Tool permissions determine whether gateable web and MCP tools pause. Core repository tools do not pause. When a run reaches **Awaiting approval**: 1. Open the approval card. 2. Review the tool, MCP server if applicable, and summarized inputs. 3. Click **Approve**, or click **Reject with note** and explain what the agent should do instead. Only an Account Admin in the same workspace can decide. A decision is recorded with the approver and time. Slack approval controls use the same authorization. If Slack asks you to link your identity, complete the one-time link before deciding. Linking does not grant the Account Admin role or approve the action. ## Artifacts A completed run can produce: * A pull or merge request * A pushed branch or compare link * A Markdown response in Agent Console * A source-control review for Custodian Open artifacts from the run detail page. Agents do not merge their own changes. Succeeded Builder run with pull request and answer artifacts # Agent Console Source: https://docs.sidecardata.com/products/agent-console/overview Configure Sidecar agents, create repeatable jobs, and review their runs The Agent Console is where you configure Sidecar agents, create jobs, and review their work. Open **Agents** in Sidecar to get started. Builder, Reliability, Optimization, and Custodian are available. Concierge appears as coming soon. You must be an Account Admin to open the Agent Console, manage its settings, or approve a gated tool action. Agent Console with Console, Builder, Reliability, Optimization, and Custodian available and Concierge marked coming soon ## How the Agent Console is organized ### Agents Each agent has a specific role. For example, Builder handles engineering work while Reliability investigates data incidents. Start with [Choose an agent](/products/agent-console/agents/choose-an-agent) to compare them. An agent's **Settings** page controls its connected MCP servers and the defaults used for Slack runs. ### Jobs A job is saved work for one agent. It contains instructions, repository scope, output settings, a trigger, MCP access, and tool permissions. You can create a custom job, install a preset, or duplicate a template. The options depend on the agent. See [Create a job](/products/agent-console/jobs/create-a-job). ### Runs A run is one execution of a job or Slack request. The **Console** lists runs across every agent. Open a run to review its progress, transcript, approvals, and artifacts. ### Resources and tools Agents can use several types of context. Each type has its own setup path: | Resource | What it provides | Where you configure it | | --------------- | ------------------------------------------------------------------- | ----------------------------------------------------------- | | Source control | Repository contents and a destination for branches or pull requests | **Integrations**, then the job's repository scope | | dbt | Project metadata, tests, and lineage | **Integrations** | | MCP servers | External tools such as warehouse query access | **Integrations → MCP Servers**, then agent and job settings | | Knowledge Store | Company context, policies, and playbooks | **Context → Knowledge Store** | Use the [Agent Console setup guide](/products/agent-console/setup/overview) to prepare these resources. ## Start here Follow a complete Builder example from setup through the first run. Compare each live agent and its intended work. Connect repositories, dbt, MCP servers, and knowledge. Send an ad hoc request by direct message. # Create your first Agent Console job Source: https://docs.sidecardata.com/products/agent-console/quickstart Create and run a Builder job that makes a reviewable documentation change In this quickstart, you create a manual Builder job that updates documentation in one repository and opens a pull request for review. ## Before you start You need: * An Account Admin role in Sidecar * Agent Console enabled for your workspace * A connected GitHub or GitLab repository where you can safely make a documentation change * Permission to review pull or merge requests in that repository If the repository is not connected, complete [Connect repositories](/products/agent-console/setup/connect-repositories) first. ## Create the job In Sidecar, select **Agents**, then select **Builder**. Builder does not ship with presets, so you create this job from scratch. Builder agent page with the New job button Click **New job**. Enter these values: | Setting | Value | | ---------------- | ---------------------------------------------------------------- | | **Name** | `Update repository documentation` | | **Description** | `Correct one small documentation issue and open a pull request.` | | **Instructions** | Use the example below. | | **Repositories** | Select one repository. | | **Delivery** | **Open a pull request** | | **Trigger** | **Manual** | ```text theme={null} Review the repository documentation for one small, clearly incorrect or outdated statement. Correct it, preserve the existing style, and validate any affected links or formatting. Do not change application code. ``` Selecting one repository keeps the first run focused. An empty repository selection means all currently accessible repositories. New Builder job populated with documentation instructions and one selected repository Click **Create job**. Sidecar opens the job configuration page. Confirm these settings before the first run: * **Scope** contains only the repository you selected. * **Completion and output** is set to **Open a pull request**. * **Schedule and trigger** is set to **Manual**. * **MCP servers** can stay at its default. This task does not require an MCP server. * **Tool permissions** is set to **Autonomous**. Autonomous mode lets gateable tools run without pausing. Core repository tools are always available. You can use **Supervised** for later jobs when you want gateable web or MCP tools to require Account Admin approval. Builder job configuration with repository scope, Manual trigger, MCP server selection, and Autonomous permissions Click **Run now**. Sidecar opens the run detail page. The run moves from **Queued** to **Running** while Builder reads the repository, makes the change, and validates it. Running scheduled Builder job with its first turn visible When the run finishes, open its artifact. Review the pull request and its checks before merging. Builder never merges its own changes. Succeeded Builder run with a pull request artifact and final answer ## Next steps * Learn how to [create jobs from presets](/products/agent-console/jobs/create-a-job#from-a-preset). * [Connect an MCP server](/integrations/mcp-servers/connect-an-mcp-server), then [give an agent access](/products/agent-console/setup/give-agents-mcp-access). * [Create a schedule](/products/agent-console/jobs/configure-a-job#schedule-and-trigger) for recurring work. * [Run an agent from Slack](/products/agent-console/run-an-agent-from-slack) for an ad hoc request. # Review upstream changes for downstream impact Source: https://docs.sidecardata.com/products/agent-console/recipes/custodian-downstream-impact-review Configure a Custodian job that reviews upstream GitHub pull requests for downstream impact In this recipe, you configure Custodian to review pull requests in one upstream GitHub repository for evidence-supported effects on one downstream repository. The job posts its findings as a source-control review. For this first setup, you use **Review only** so Custodian does not change downstream code. ## Before you start You need: * An Account Admin role in Sidecar * Permission to install or configure GitHub apps for the relevant organizations * One upstream GitHub repository that receives changes * One different downstream GitHub repository that may depend on those changes * The standard Sidecar Data GitHub app connected to the downstream repository * The Custodian GitHub app installed with access to the upstream repository Both repositories must use `github.com`. ## Configure the GitHub integrations In Sidecar, select **Integrations → GitHub**. If the standard Sidecar Data GitHub app is not connected, click **Link Sidecar Data** and grant it access to the downstream repository. On the same GitHub integration page, find **Custodian** and click **Manage access in GitHub**. Install or configure the Custodian GitHub app with access to the upstream repository. If GitHub shows an approval request, ask an organization administrator to approve it. Return to Sidecar and confirm that the Custodian installation lists the upstream repository as accessible. ## Subscribe the upstream repository Select **Agents → Custodian**, then click **Settings**. Under **Scope → Subscribed repositories**, find the upstream repository and click **Bind**. You can use **Bind all accessible** when every accessible repository should be available as a Custodian upstream. Confirm that the repository shows as bound and accessible. ## Duplicate the Custodian template Return to the Custodian page and click **From preset**. Find **Review changes for downstream impacts** and click **View template**. The template is read-only and never runs directly. Click **Duplicate**. Sidecar creates an inactive custom copy and opens its configuration page. Immutable Custodian downstream-impact review template with Duplicate button ## Configure the review job Use a name that identifies the repository relationship, such as `API changes → analytics impact review`. Add a description that helps Account Admins recognize the job in the Console. Keep the default instructions for the first job. Add only constraints specific to this upstream and downstream relationship. Under **Scope**, select: * **Upstream repository** — the repository you bound to Custodian * **Downstream repository** — the different repository connected through the standard Sidecar GitHub integration Save the scope. Under **Review behavior**, select **Review only**. Leave **Suppress no-findings comments** off for the first test. This lets you confirm that the workflow ran even when it finds no downstream impact. After validating the workflow, you can choose **Draft PR when a safe fix is verified**. Confirm that the readiness panel marks the upstream and downstream repositories ready. Knowledge Store and Context Garage checks are informational. They do not block activation. Switch the job to **Active**. Sidecar allows only one active Custodian downstream-impact job for a given upstream repository. If activation fails, pause the existing job or choose another upstream. ## Test the workflow Create a safe test pull request in the upstream repository, or push a new commit to an existing test pull request. Custodian starts from the GitHub pull-request webhook. This job does not have **Run now**. Open **Agents → Console** and select the Custodian run. Review the evidence, findings, and delivery status. Return to the upstream pull request and find the Custodian review comment. With **Review only**, Custodian does not change downstream code. If you later enable draft remediation, review any downstream draft pull request before merging. ## Maintain the job * Pause the job before changing a repository binding. * Restore GitHub app access if readiness reports an inaccessible repository. * Use **Retry** when the same pull-request snapshot should run again. * Use **Run again** when the upstream head or downstream base branch has moved. # Run an agent from Slack Source: https://docs.sidecardata.com/products/agent-console/run-an-agent-from-slack Send an ad hoc Agent Console request by direct message to the Sidecar Slack app Send a direct message to the Sidecar Slack app when you need an agent to handle an ad hoc request without creating a job. Agent Console requests are supported only in direct messages. Messages and mentions in Slack channels do not start Agent Console runs. ## Before you start Your workspace must have the [Sidecar Slack app connected](/integrations/communication/slack). Any human member of the connected Slack workspace can start a run. You do not need a linked Sidecar user account to send the request. ## Send a request In Slack, find **Sidecar** under **Apps** and open its direct-message conversation. Send a plain-text request. You do not need to mention the app or name an agent. Include the target, expected result, and relevant constraints. For example: ```text theme={null} Investigate why the orders freshness check failed this morning. Identify the most likely cause and recommend the smallest safe next step. Do not change code or data. ``` Reply in the same Slack thread when the agent asks for clarification or when you want to add context. Follow-up messages stay attached to the same run and do not select a different agent. ## How Sidecar chooses an agent Sidecar classifies the first message against the agents available to your workspace. It falls back to Builder when the request is empty, classification fails, or no agent reaches the confidence threshold. Sidecar does not show a persona-selection prompt. Write the request clearly when you want a specialist, such as Reliability for an incident or Optimization for warehouse cost analysis. ## Settings used by Slack runs The selected agent's **Settings → Run defaults** supply its delivery mode and tool permissions. The run can use every MCP server granted under **Connected tools**. See [Configure agent defaults](/products/agent-console/setup/configure-agent-defaults). ## View the run in Agent Console Slack-started runs appear in the Agent Console with Slack as their origin. Account Admins can open the run, inspect its transcript, cancel it, and manage approvals. Sending a Slack request does not grant the sender access to Agent Console. ## Approve from Slack When a gateable tool pauses, Sidecar can send approval controls in Slack. The approver must: * Link their Slack identity when prompted * Belong to the same Sidecar workspace * Have the Account Admin role The link is single use and expires after 15 minutes. It identifies the Slack user; it does not grant a role or make an approval decision. See [Runs and approvals](/products/agent-console/jobs/runs-and-approvals#approvals) for approval behavior. # Configure agent defaults Source: https://docs.sidecardata.com/products/agent-console/setup/configure-agent-defaults Set the scope and run defaults used by Agent Console Slack requests Each agent has default settings for runs that do not use a job. Today, these defaults apply to requests sent by direct message to the Sidecar Slack app. Job settings are independent. Changing an agent default does not update existing jobs or active runs. ## Open agent settings 1. In Sidecar, select **Agents**. 2. Open an agent. 3. Click **Settings**. Changes on this page save automatically and affect future runs. Builder settings with repository scope, connected Snowflake tool, and run defaults ## Scope The **Scope** section shows: * **Repositories** available from the connected source-control provider * **Connected tools** granted from the workspace MCP registry * **Subscribed repositories** for Custodian only Use [Give agents MCP access](/products/agent-console/setup/give-agents-mcp-access) to manage connected tools. ## Run defaults ### Delivery Delivery options depend on the agent's resource requirements. They can include a pull request, branch, or text response. ### Tool permissions * **Autonomous** runs gateable tools without approval unless you add an exception. * **Supervised** pauses gateable tools for Account Admin approval unless you add an exception. Exceptions can include web tools and whole MCP servers. Core repository tools do not pause. These settings apply to [Slack runs](/products/agent-console/run-an-agent-from-slack). A saved job uses its own delivery, MCP selection, and tool permissions. # Connect dbt context Source: https://docs.sidecardata.com/products/agent-console/setup/connect-dbt Connect dbt metadata and the matching code repository for Agent Console A dbt integration gives Sidecar project metadata, tests, run results, and lineage. It does not give an agent access to your dbt code. Most dbt workflows need two independent connections: 1. Connect dbt Core or dbt Cloud for metadata. 2. Connect GitHub or GitLab for repository access. ## Connect dbt metadata Use the guide for your deployment: Upload `manifest.json` and `run_results.json` manually or from CI. Connect an organization service account to the dbt Cloud APIs. ## Enable dbt Cloud tools For live job inspection, model diagnostics, and run retries, [enable dbt Cloud MCP](/integrations/mcp-servers/dbt-cloud), then grant it to the agent. This is a separate step from connecting dbt metadata and does not provide repository access. ## Connect the code repository Follow [Connect repositories](/products/agent-console/setup/connect-repositories), then confirm that the repository containing the dbt project appears under the agent's **Settings → Scope**. When you configure a dbt-focused job, select that repository explicitly. This lets the agent connect Sidecar's dbt evidence to the code it can inspect or change. A report-only job may use dbt evidence without a repository. A job that needs to prepare a code change must have repository access. # Connect repositories Source: https://docs.sidecardata.com/products/agent-console/setup/connect-repositories Give Agent Console access to repositories through GitHub or GitLab Agent Console gets repository access from your source-control integration. Connect the provider once, then choose all repositories or a subset when you create a job. Choose your provider: Install and configure the Sidecar Data GitHub app. Authorize Sidecar through GitLab OAuth. Agent Console uses one source-control provider for repository operations. If both GitHub and GitLab are connected, Agent Console uses GitLab. ## Verify repository access 1. In Sidecar, select **Agents**. 2. Open an agent. 3. Click **Settings**. 4. Review **Scope → Repositories**. The list reflects the repositories currently available through the connected provider. Change access in GitHub or GitLab, then return to Sidecar to refresh the list. Builder settings with connected repositories listed under Scope ## How jobs use repository scope When you create a custom job, an empty **Repositories** selection means all accessible repositories. Sidecar resolves that list again when the job runs, so newly connected repositories join the scope automatically. For a narrower and more predictable job, select only the repositories it needs. See [Configure a job](/products/agent-console/jobs/configure-a-job#repository-scope). Custodian uses a separate upstream subscription in addition to the standard GitHub integration. Follow the [Custodian recipe](/products/agent-console/recipes/custodian-downstream-impact-review) for that workflow. # Give agents MCP access Source: https://docs.sidecardata.com/products/agent-console/setup/give-agents-mcp-access Grant registered MCP servers to agents and select the servers each job can use Register an MCP server once, grant it to an agent, and then choose whether each job can use it. If the server is not registered yet, follow [Connect an MCP server](/integrations/mcp-servers/connect-an-mcp-server). ## Grant a server to an agent 1. In Sidecar, select **Agents**. 2. Open the agent that needs the server. 3. Click **Settings**. 4. Under **Scope → Connected tools**, select the MCP server. Changes save automatically. A status dot shows the server's latest known health. Builder settings with Snowflake selected under Connected tools The grant sets the maximum MCP access for that agent. Jobs cannot enable a server that the agent has not been granted. Removing a grant also removes that server from the agent's job selections and tool-permission exceptions. ## Select servers for a job 1. Open the agent's job. 2. Find **MCP servers**. 3. Leave all granted servers enabled, or clear the servers this job should not use. By default, a job uses all MCP servers currently granted to its agent. This includes servers granted later. Once you create an explicit selection, the job uses only that saved subset. Builder job with Snowflake enabled in the MCP servers section and Autonomous tool permissions ## Configure approvals for an MCP server MCP permissions apply to the entire server rather than individual discovered tools. Under **Tool permissions**: * **Autonomous** lets gateable tools run automatically. Add an MCP server as an exception when that server should pause for approval. * **Supervised** pauses gateable tools for Account Admin approval. Add an MCP server as an exception when that server may run automatically. Core repository tools remain available in either mode. See [Runs and approvals](/products/agent-console/jobs/runs-and-approvals#approvals) for the approval flow. ## Slack runs A Slack run can use every MCP server granted to the selected agent. It uses the permissions under the agent's **Settings → Run defaults**, not a job's MCP selection or permissions. # Set up Agent Console Source: https://docs.sidecardata.com/products/agent-console/setup/overview Prepare repositories, dbt context, MCP tools, knowledge, and agent defaults Agent Console setup spans several parts of Sidecar. Complete only the connections required by the agents and jobs you plan to use. ## Setup checklist Give agents access to GitHub or GitLab repositories. Sync dbt metadata independently from repository access. Register external tools at the workspace level. Grant a registered server to an agent and its jobs. Add company context and playbooks to the Knowledge Store. Set delivery and tool permissions for Slack runs. ## Resource requirements by agent | Agent | Repositories | Warehouse MCP | Special setup | | ------------ | ------------------ | ----------------------------------- | ------------------------------------------- | | Builder | Required | Optional | None | | Reliability | Optional | Optional | Monitor preset is event driven | | Optimization | Depends on the job | Required for expensive query review | dbt integration for project-health evidence | | Custodian | Required | Optional | Custodian GitHub app and repository binding | Sidecar shows readiness on each job. A required resource blocks the job until you connect it. An optional resource can improve the result without blocking the run. You must be an Account Admin to manage Agent Console integrations and settings. # Provide knowledge to agents Source: https://docs.sidecardata.com/products/agent-console/setup/provide-knowledge Add company context, policies, and playbooks to the Knowledge Store Agent Console automatically makes your synchronized Knowledge Store available to agent runs. You do not attach knowledge to individual agents or jobs. ## Initialize the Knowledge Store 1. In Sidecar, select **Context → Knowledge Store**. 2. If no store exists, click **Initialize Knowledge Store**. 3. Wait for the bootstrap to finish. You can leave the page while it runs. ## Add useful context Create or upload Markdown, text, or YAML files. Good candidates include: * Company and product terminology * Data ownership and escalation policies * Engineering conventions * Incident-response playbooks * Metric definitions and business nuances Organize related files into folders so people can maintain them over time. A missing Knowledge Store does not block a run. The agent continues without that context. Context Garage is separate from the Knowledge Store. It publishes structured data context to downstream tools; it is not a general per-job knowledge attachment. # Ask Sidecar with Snowflake query execution Source: https://docs.sidecardata.com/products/agents/ask-sidecar-snowflake Enable Ask Sidecar to run read-only queries against your Snowflake warehouse Ask Sidecar can query your Snowflake warehouse directly to answer data questions in natural language. This guide walks through the setup. ## How Snowflake MCP works Snowflake supports [MCP Servers](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp) as a native database object. An MCP Server is created once inside a Snowflake database by an admin, and it exposes a read-only SQL execution tool that any authorized Snowflake user can call. The setup has two parts: 1. **Admin (once per org):** Create the MCP Server object in Snowflake and verify it in Sidecar. This makes query execution available to your organization. 2. **Each user:** Connect a personal Snowflake Programmatic Access Token (PAT). Queries run under each user's own Snowflake identity, so existing role-based access controls are respected. ## Prerequisites To complete the admin steps you need: 1. The [Snowflake integration](/integrations/data-warehouses/snowflake) connected in Sidecar 2. Account Admin permissions in Sidecar 3. The ACCOUNTADMIN role in Snowflake Individual users only need a Snowflake account that can generate a PAT. ## Admin setup These steps are performed once per organization. ### 1. Open the Ask Sidecar tab 1. In the Sidecar app, go to **Integrations** > **Snowflake**. 2. Switch to the **Ask Sidecar** tab. This tab is only available after Snowflake credentials have been saved on the Connection tab. ### 2. Choose a database The MCP Server object will be created inside a Snowflake database. The default is `SIDECAR_DATABASE`, the same database created during the Snowflake integration setup. If you'd like to use a different database, enter the name and click **Confirm** before continuing. ### 3. Run the setup SQL in Snowflake Sidecar generates the SQL you need to run. Click the copy button and execute the following in a Snowflake worksheet: ```sql theme={null} USE ROLE ACCOUNTADMIN; CREATE OR REPLACE MCP SERVER .PUBLIC.SIDECARMCPSERVER FROM SPECIFICATION $$ tools: - name: "executesql" type: "SYSTEM_EXECUTE_SQL" title: "SQL Execution" description: "Execute read-only SQL queries against Snowflake." config: read_only: true $$; GRANT USAGE ON MCP SERVER .PUBLIC.SIDECARMCPSERVER TO ROLE PUBLIC; DESCRIBE MCP SERVER .PUBLIC.SIDECARMCPSERVER; ``` Replace `` with the database name from Step 2 (e.g., `SIDECAR_DATABASE`). The Sidecar UI pre-fills this for you. This SQL does three things: 1. Creates an MCP Server object named `SIDECARMCPSERVER` with a single read-only SQL execution tool. 2. Grants usage on the MCP Server to the `PUBLIC` role so all users in your Snowflake account can authenticate against it with their own PAT. 3. Runs `DESCRIBE` to confirm the object was created. The `GRANT USAGE ... TO ROLE PUBLIC` statement allows all Snowflake users to access the MCP Server. If you need to restrict access, grant to a specific role instead. ### 4. Verify the MCP Server Back in Sidecar, click **Verify MCP Server**. Sidecar connects to your warehouse and runs `DESCRIBE MCP SERVER` to confirm the object exists. Once verified, a green checkmark appears and the per-user token setup section becomes available for all users in your organization. ### 5. Allow Sidecar through your network policy Snowflake requires users who authenticate with Programmatic Access Tokens to be subject to a network policy with at least one network rule by default. Sidecar sends Snowflake MCP requests from this production outbound IP address: ```text theme={null} 44.236.246.98/32 ``` First, identify the network policy that applies to each Snowflake user who will connect a PAT. A user-level policy overrides an account-level policy. ```sql theme={null} SHOW PARAMETERS LIKE 'NETWORK_POLICY' FOR USER ; SHOW PARAMETERS LIKE 'NETWORK_POLICY' IN ACCOUNT; ``` If a policy applies, inspect whether it uses network rules or the legacy IP allowlist: ```sql theme={null} DESCRIBE NETWORK POLICY ; ``` For a rule-based or new policy, create a network rule for Sidecar in the database selected in Step 2: ```sql theme={null} USE ROLE ACCOUNTADMIN; CREATE NETWORK RULE .PUBLIC.SIDECAR_MCP_INGRESS MODE = INGRESS TYPE = IPV4 VALUE_LIST = ('44.236.246.98/32') COMMENT = 'Sidecar production outbound IP for Snowflake MCP'; ``` Add the rule to an existing rule-based policy without replacing its other rules: ```sql theme={null} ALTER NETWORK POLICY ADD ALLOWED_NETWORK_RULE_LIST = ('.PUBLIC.SIDECAR_MCP_INGRESS'); ``` If no rule-based policy applies, create one that includes both Sidecar and your normal corporate or VPN ingress rule, then attach it to the user: ```sql theme={null} CREATE NETWORK POLICY SIDECAR_ASK_NETWORK_POLICY ALLOWED_NETWORK_RULE_LIST = ( '.PUBLIC.SIDECAR_MCP_INGRESS', '..' ); ALTER USER SET NETWORK_POLICY = SIDECAR_ASK_NETWORK_POLICY; ``` A policy that allows only Sidecar's IP blocks the user from connecting directly from other networks. Include every allowed and blocked rule required by your organization for Snowsight and other Snowflake clients before attaching the policy. If `DESCRIBE NETWORK POLICY` shows `ALLOWED_IP_LIST` instead of `ALLOWED_NETWORK_RULE_LIST`, do not add the Sidecar rule to that legacy policy. Snowflake requires network rules for PAT access and recommends against mixing legacy IP lists with network rules. Create a rule-based user policy that reproduces every required allowed and blocked restriction, then add the Sidecar rule and attach the new policy. Coordinate this change with your Snowflake security administrator to avoid locking users out. Do not use **Bypass requirement for network policy** for ongoing Sidecar access. The bypass is temporary and does not bypass an existing network policy. See Snowflake's [programmatic access token guide](https://docs.snowflake.com/en/user-guide/programmatic-access-tokens#network-policy-requirements) and [network policy guidance](https://docs.snowflake.com/en/user-guide/network-policies). ## Per-user setup Once the admin has created the MCP Server object, each user connects their own Snowflake PAT. This is what allows Ask Sidecar to run queries on your behalf, under your Snowflake identity. ### 6. Generate a Programmatic Access Token (PAT) 1. Log in to Snowflake and click your user icon in the bottom left. 2. Navigate to **Settings** > **Authentication** > **Programmatic access tokens**. 3. Click **Generate token**, select a validity period, then click **Generate**. 4. Copy the token immediately. It is only shown once. ### 7. Connect the token in Sidecar 1. In the Sidecar app, go to **Integrations** > **Snowflake** > **Ask Sidecar** tab. 2. Paste your PAT into the **Programmatic Access Token** field. 3. Click **Connect**. Open **Ask Sidecar** from the sidebar and start asking questions. The agent can now run read-only SQL queries against your Snowflake warehouse on your behalf. ## Managing your connection ### Disconnect your token 1. Go to **Integrations** > **Snowflake** > **Ask Sidecar** tab. 2. Click **Disconnect**. You can reconnect at any time by generating a new PAT and repeating Step 6. ### Rotate your token Disconnect the current token, generate a new one in Snowflake, and connect the new token. ## How queries are executed When you ask a data question, Ask Sidecar's agent decides whether a Snowflake query would help answer it. If so: 1. The agent writes a SQL query. Only `SELECT`, `WITH`, `SHOW`, and `DESCRIBE` statements are allowed. 2. The query runs against your Snowflake warehouse using your PAT. Your Snowflake role determines what data is accessible. 3. Results come back to the agent, which interprets and summarizes them in the chat. All queries are read-only. The MCP Server is provisioned with `read_only: true` in Snowflake, and Sidecar enforces this independently at the proxy layer. ## Troubleshooting The MCP Server object has not been created in Snowflake yet, or it hasn't been verified in Sidecar. Ask your Sidecar admin to complete the admin setup steps above. Confirm you ran the setup SQL as ACCOUNTADMIN and that the database name in the SQL matches the name shown in Sidecar. The `DESCRIBE MCP SERVER` statement at the end of the SQL should return results without errors. If it doesn't, the MCP Server object was not created. Make sure your token is a Programmatic Access Token (from **Settings → Authentication → Programmatic access tokens**), not an OAuth token or password. Confirm that the effective network policy allows `44.236.246.98/32` and that the authentication policy permits `PROGRAMMATIC_ACCESS_TOKEN`. If the token was copied incorrectly, generate a new one because PATs cannot be retrieved after creation. Queries run under your Snowflake identity. If you can't see certain tables in Ask Sidecar, check that your Snowflake role has SELECT access to those tables. # Contract Agent quickstart Source: https://docs.sidecardata.com/products/agents/contract-agent Set up Sidecar's GitHub-integrated PR reviewer for data contract changes Use this guide to install the Contract Agent and verify that it reviews pull requests for data contract changes. ## What is the Contract Agent? The Contract Agent is a GitHub-integrated PR reviewer that automatically analyzes pull requests for data contract changes. When a PR modifies dbt models or schema files, the Contract Agent evaluates the downstream impact and posts a review comment. ## Prerequisites * A Sidecar account with the **Contract Agent** feature enabled * **Account Admin** role in Sidecar * **dbt** connected to Sidecar * **Admin access** to the GitHub repository you want to monitor ## 1. Install the GitHub App 1. In the Sidecar app, go to the **Integrations** page. 2. Find the **GitHub** integration. 3. Click **Configure Contract Agent in GitHub**. 4. You will be redirected to GitHub to install the Sidecar GitHub App. 5. Select the organization and repositories you want the Contract Agent to monitor. 6. Click **Install**. ## 2. Verify the installation Create a test pull request that modifies a dbt model or schema file. After a few moments: 1. A **check run** should appear on the PR. 2. A **review comment** should be posted with the Contract Agent's analysis. The Contract Agent's findings are informational. They do not result in a failing GitHub Check. ## Managing the installation ### Add or remove repositories 1. Go to your GitHub organization's **Settings** > **GitHub Apps**. 2. Find the **Sidecar** app and click **Configure**. 3. Under **Repository access**, add or remove repositories as needed. ### Pause the Contract Agent To temporarily stop the Contract Agent from reviewing PRs, contact the Sidecar team via your dedicated Slack channel. ### Uninstall 1. Go to your GitHub organization's **Settings** > **GitHub Apps**. 2. Find the **Sidecar** app and click **Configure**. 3. Click **Uninstall**. ## Troubleshooting * Verify the GitHub App is installed on the correct repository. * Ensure the PR modifies a dbt model or schema file that Sidecar tracks. * Check that the Contract Agent feature is enabled in your Sidecar account. The Contract Agent determined that the PR does not contain changes relevant to data contracts. No action is needed. This indicates an internal error. Contact the Sidecar team via your dedicated Slack channel or at [support@sidecardata.com](mailto:support@sidecardata.com). If the Contract Agent is flagging too many changes, reach out to the Sidecar team to tune the sensitivity for your project. # Sidecar Engineer for Jira quickstart Source: https://docs.sidecardata.com/products/agents/sidecar-engineer/jira-quickstart Start Sidecar Engineer by assigning a Jira issue to Sidecar Use Sidecar Engineer for Jira when your team wants Sidecar to work from a Jira issue and report progress back in Jira comments. ## Before you start You need: * A Sidecar workspace with Jira connected * A dedicated Jira identity for Sidecar * The Sidecar Jira identity assigned to the target Jira projects * The Sidecar GitHub App installed on repositories Sidecar may update * A Jira webhook configured for Sidecar Engineer events Sidecar can publish a preliminary plan without repository access, but it cannot implement code changes until the Sidecar GitHub App is installed on the relevant repositories. ## Set up Jira Create an Atlassian service account for Sidecar. If you cannot use a service account, create a separate Atlassian account with a distinct email address or alias. Do not reuse a human user's Atlassian account. Create a Jira API token for the Sidecar identity. The token needs effective access for: * `read:jira-user` * `read:jira-work` * `write:jira-work` In Sidecar, connect Jira with the Sidecar Jira identity's email, API token, and Jira cloud ID. Sidecar uses that Jira identity to detect assignments, recognize real `@Sidecar` mentions, and post plan or delivery comments. In every Jira project where Sidecar should work, grant the Sidecar identity permission to browse issues, be assigned issues, and add comments. In Jira, go to **Settings** > **System** > **WebHooks** and create a webhook. Use this URL: ```text theme={null} https://service-platform.sidecardata.com/api/v1/tools/webhooks/jira/managed-agents/ ``` Select these events: * `jira:issue_updated` * `comment_created` * `comment_updated` Scope the webhook to the projects where Sidecar should work. If your Jira webhook configuration supports field filters, restrict issue updates to assignee changes. Configure a shared secret or HMAC signing secret for the webhook, then save the same secret in the Sidecar Jira integration. ## Start work Add the request, acceptance criteria, and relevant constraints to the issue. You do not need to name the target repository unless the request is ambiguous. Assign the issue to the dedicated **Sidecar** Jira identity. This starts Sidecar's first analysis turn when there is not already an open Sidecar workflow for that issue. Sidecar comments with a plan, clarification question, setup blocker, validation failure, or pull request link. No separate approval comment is required before implementation. If the request is clear and setup is ready, Sidecar can start implementation automatically. Add a new comment that explicitly mentions Sidecar. ```text theme={null} @Sidecar preserve backward compatibility for the existing dashboard ``` Create a new comment for each clarification or rework request. Do not edit an old comment to give new instructions. When implementation succeeds, Sidecar comments with one or more pull request links. Review, request changes, and merge through your normal GitHub process. ## Behavior to know * Comments without a Sidecar mention are ignored by the agent. * Editing old comments is audit-only in this version. * Editing issue fields does not wake Sidecar by itself. Add a new `@Sidecar ...` comment after changing the issue. * Moving the assignee away from Sidecar does not cancel an existing workflow. * Later `@Sidecar ...` comments can trigger clarification, rework, or another implementation pass. * If a rework request expands scope or changes the repository set, Sidecar runs analysis again before making more code changes. * If implementation spans multiple repositories, Sidecar groups the pull request links in one Jira comment. ## Troubleshooting Confirm the issue was assigned to the dedicated Sidecar Jira identity, the webhook includes `jira:issue_updated`, the webhook secret matches Sidecar's Jira integration, and the Sidecar identity can browse and comment in the project. Add a new comment that explicitly mentions Sidecar. Comments without a Sidecar mention and edited old comments do not drive the workflow. Follow the blocker in Sidecar's comment. The most common blocker is missing Sidecar GitHub App access for the repository Sidecar needs to inspect or update. # Context Garage key concepts Source: https://docs.sidecardata.com/products/context-garage/key-concepts Learn how Context Garage turns your data catalog into versioned semantic context for analytics and AI tools Context Garage helps you create, edit, publish, and serve semantic context for your data. It starts from your Sidecar catalog, generates a repo of YAML files, and lets you maintain that repo directly in the browser. ## Context repo A context repo is the file-backed workspace for one semantic context project. The repo contains files such as: * `sidecar_repo.yml` for repo settings and file locations * `datasets/*.osi.yml` for datasets and fields * `relationships/_relationships.yml` for joins between datasets * `metrics/_metrics.yml` for shared metric definitions The files are the authoring state. When you edit a dataset, relationship, or metric, you are editing the repo files, not a separate intermediate model. ## Draft A draft is the mutable version of the repo. Changes from file edits, asset selection updates, and catalog syncs are saved to the draft until you publish them. Use the draft to review generated files, make manual edits, and confirm the repo is ready before creating an immutable version. ## Version A version is an immutable snapshot of the repo, named with a simple increment such as `v0`, `v1`, or `v2`. Publishing a draft creates the next version. Published versions can be downloaded, served by MCP, or deployed to supported targets such as Snowflake Cortex. ## Generated artifacts When you publish or preview a repo, Sidecar can generate export artifacts from the repo files. Common artifacts include: * Source OSI, which preserves the Sidecar-native repo representation * Clean OSI, which is the normalized OSI representation for consumption * Cortex YAML, which is formatted for Snowflake semantic views These artifacts are generated from the files in the repo. They are not hand-maintained separately. ## Deploy surface A deploy surface is a durable target that serves a published version. Examples include: * An MCP endpoint used by AI tools * A Snowflake Cortex semantic view target A deploy surface can track the latest published version or pin to a specific version. ## Deployment A deployment is the event of applying a published version to one or more deploy surfaces. Deployments capture what version was served, which surface received it, whether the rollout succeeded, and any target-specific result metadata. ## Download Download is an export action, not a deploy surface. You can download a published version when you need the generated YAML for a self-managed workflow. ## Catalog sync Context Garage can keep a repo aligned with selected catalog assets. You can update the selected assets later. New selected tables are added to the draft, removed tables are deleted from the draft, and existing dataset files are left in place so manual edits are not overwritten. Future inclusion rules can also add newly discovered catalog assets that match your selected scope. # Context Garage quickstart Source: https://docs.sidecardata.com/products/context-garage/quickstart Create your first context repo, publish a version, and serve it to downstream tools Use this guide to create a context repo from catalog assets, review the generated files, publish a version, and make it available to another tool. ## Before you start You need: * A Sidecar workspace with Context Garage enabled * A connected warehouse with catalog assets synced into Sidecar * Permission to create and publish context repos ## Create a context repo In Sidecar, open **Context Garage** from the main navigation. Context Garage empty state with Build your first repo button Click **Build your first repo**. Sidecar opens the **Build a context repo** wizard. Choose the Catalog tables this repo should track. You can select individual tables or select a broader database or schema scope. To include matching tables that are discovered later, enable **Future** for the selected scope. Three-column asset selector with databases, schemas, tables, selected rows, and Future controls Click **Next: Sync behavior**. Choose whether Sidecar should auto-apply Catalog drift to tracked repo files. When **Metadata sync** is enabled, Sidecar can update the draft for column adds and removals, type changes, table deletions, and description updates. You can override this behavior later inside the repo. Sync behavior step with the Metadata sync toggle enabled Click **Next: Name & create**. Enter a repo name and optional description. The description appears on the repo card and inside the Build view. Name your repo step with repo name, description, and Create and Bootstrap button Click **Create & Bootstrap**. Sidecar reads the Catalog and available dbt SQL, generates the initial repo files, and creates a draft repo. Bootstrap is durable. You can leave the page and return later while it runs. Bootstrap progress page with stages for reading Catalog metadata, identifying dimension and fact columns, materializing semantic files, and finalizing the repo ## Review and edit files Use the file navigator to open generated files and review the YAML. Common first edits include: * Update dataset and field descriptions * Mark important fields as dimensions, facts, or time dimensions * Add relationships between datasets * Add shared metrics Context Garage file navigator with a dataset YAML file open in the editor ## Publish a version When the draft is ready, publish it. Click **Publish** from the repo editor. Review the generated OSI and target-specific artifacts, such as Cortex YAML. Add an optional message and click **Publish version**. Sidecar creates the next immutable version, such as `v0` or `v1`. Publish dialog showing generated artifacts and the next version number ## Serve the published version After publishing, choose how to use the version. Download the generated OSI or target-specific YAML for a self-managed workflow. Create an MCP deploy surface and generate a token for AI tools that support MCP. Create a Cortex deploy surface to push the generated semantic view YAML to Snowflake. Configure a deploy surface to track the latest published version so new versions are served automatically. Deploy surfaces page with MCP, Cortex, and download options ## Keep the repo current As your catalog changes, return to the asset selector to update what the repo tracks. When you save selection changes: * Newly selected tables are added to the draft * Unselected tables are removed from the draft * Existing dataset files remain in place * Future inclusion rules continue to add matching new assets Publish a new version when the draft is ready for downstream tools. # Quickstart Source: https://docs.sidecardata.com/quickstart A typical onboarding flow for connecting your data stack to Sidecar ## Typical Setup Order Most teams connect their tools in this order: Start with [Snowflake](/integrations/data-warehouses/snowflake), [BigQuery](/integrations/data-warehouses/bigquery), [Redshift](/integrations/data-warehouses/redshift), or [Databricks](/integrations/data-warehouses/databricks). This is where Sidecar discovers your tables, views, and query history. Add [dbt Cloud](/integrations/transformation/dbt-cloud) or [dbt Core](/integrations/transformation/dbt-core) so Sidecar can map your models, tests, and lineage. Add [Looker](/integrations/bi-analytics/looker), [Metabase](/integrations/bi-analytics/metabase), [Power BI](/integrations/bi-analytics/power-bi), [Lightdash](/integrations/bi-analytics/lightdash), or [Omni](/integrations/bi-analytics/omni) to see dashboard-to-table lineage. Add [Slack](/integrations/communication/slack) or [Microsoft Teams](/integrations/communication/ms-teams) to enable alerts and thread anchoring. Add [Jira](/integrations/project-management/jira) or [Linear](/integrations/project-management/linear) to create tickets from Slack threads using the Sidecar bot. You don't need to connect everything at once. Each integration works independently — add them as your team is ready.