Overview

MC Bridge is a lightweight local server that securely bridges the Monte Carlo frontend to your data warehouse. It runs on your machine and proxies SQL queries from SQL Notebooks to your warehouse connections, enabling interactive query execution directly in the browser.

📝 MC Bridge must be running for SQL Notebook queries to execute. If the bridge is not detected, notebooks will show a connection error.

Requirements

• macOS (only supported platform currently)
• Python 3.10+
• uv package manager (install uv)

Installation

Install and run MC Bridge using uvx. Choose the extras for your warehouse:

# Snowflake
uvx --from "mc-bridge[snowflake] @ git+https://github.com/monte-carlo-data/mc-bridge.git" mc-bridge-server

# BigQuery
uvx --from "mc-bridge[bigquery] @ git+https://github.com/monte-carlo-data/mc-bridge.git" mc-bridge-server

# Redshift
uvx --from "mc-bridge[redshift] @ git+https://github.com/monte-carlo-data/mc-bridge.git" mc-bridge-server

This downloads and runs the latest version of MC Bridge with the appropriate warehouse driver. No manual cloning or pip install required.

Configuration

dbt Profiles (Automatic)

If you have a dbt profiles.yml, MC Bridge automatically imports your warehouse connections on startup. No additional flags are needed.

Manual Configuration

If you don't use dbt, create a configuration file at ~/.mc-bridge/config.yaml with your connector details:

connectors:
  # Snowflake — browser SSO (default)
  my-snowflake:
    type: snowflake
    account: myaccount.us-east-1
    user: [email protected]
    warehouse: COMPUTE_WH
    database: MY_DB           # optional
    schema: PUBLIC            # optional
    role: MY_ROLE             # optional
    # method: externalbrowser # default — opens browser for SSO
    # method: password        # requires: password
    # method: keypair         # requires: private_key_path (or private_key)

  # BigQuery — Application Default Credentials
  my-bigquery:
    type: bigquery
    project: my-gcp-project
    dataset: my_dataset       # optional
    location: US              # optional
    # method: oauth           # default — uses gcloud auth application-default login
    # method: service-account # requires: keyfile

  # Redshift — password auth
  my-redshift:
    type: redshift
    host: my-cluster.us-east-1.redshift.amazonaws.com
    user: admin
    database: mydb
    password: mypassword
    schema: public            # optional
    # method: database        # default — user/password
    # method: iam             # uses AWS credential chain

Running

Start MC Bridge using the same uvx command from Installation. On successful startup, you'll see output like:

MC Bridge is running at https://localhost:8765

MC Bridge serves over HTTPS on localhost:8765. On first run, it generates a local SSL certificate and may prompt for your system password to trust the certificate authority.

📝 Keep the MC Bridge terminal running while using SQL Notebooks. Closing the terminal stops the bridge and disconnects notebooks from your warehouse.

Supported Warehouses

• Snowflake — username/password and browser-based (externalbrowser) authentication
• BigQuery — application default credentials or service account key
• Redshift — username/password authentication

Troubleshooting

• "Bridge not connected" in notebooks: Ensure MC Bridge is running in a terminal window and that https://localhost:8765 is accessible
• Certificate errors: On first run, MC Bridge installs a local CA certificate. If prompted, allow the system trust store update. You can verify by visiting https://localhost:8765 in your browser
• dbt profile import fails: Ensure your profiles.yml is valid and the target profile exists. MC Bridge supports the same connection fields as dbt