Wire Up the AI Agent | Bruin Academy

Connect the AI agent

1. Register Bruin MCP in your AI tool

Pick the tab that matches the tool you're using. Bruin MCP is stateless - register it once per machine, not per project.

Claude Code

Run this once in your terminal:

claude mcp add bruin -- bruin mcp

Restart your Claude Code session - MCP servers are loaded at session start, so the change won't apply until you open a new one.

To verify, ask Claude Code: "Use the Bruin MCP to list the available bruin commands." It should reply with a list pulled from bruin_get_overview rather than guessing.

Cursor

Open Cursor Settings (Cmd/Ctrl + ,)
Navigate to MCP & Integrations
Click Add Custom MCP
Paste:

{
  "mcpServers": {
    "bruin": {
      "command": "bruin",
      "args": ["mcp"]
    }
  }
}

Restart Cursor.

To verify, ask Cursor's chat: "Use the Bruin MCP to fetch the docs for bruin import database." It should pull the doc page via bruin_get_doc_content.

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.bruin]
command = "bruin"
args = ["mcp"]

Restart Codex.

To verify, ask Codex: "Use Bruin MCP to list connection types Bruin supports." It should return the list from bruin_get_doc_content.

2. Confirm `bruin query` works as the agent will use it

Run a sanity-check query against your warehouse using the scoped config, exactly the way the agent will:

bruin query \
  --config-file context/.bruin.yml \
  --connection contoso_dbt_bq \
  --query "SELECT category_name, SUM(revenue_usd) AS rev
           FROM \`bruin-playground-arsalan.contoso_dbt_reports.rpt_revenue_by_segment\`
           WHERE year = 2024
           GROUP BY 1
           ORDER BY rev DESC
           LIMIT 10"

You should get a small result table back. Because the connection uses Application Default Credentials, no keyfiles change hands - the agent runs SQL as your gcloud auth application-default login identity.

3. Add an `AGENTS.md` at the repo root

Create AGENTS.md next to dbt_project.yml (the repo root, not inside context/). AI coding tools auto-load this file at session start, so it's the canonical place for "how to use this project". Adapt the paths and connection name to your setup:

# AGENTS.md

This repo contains a dbt project plus a Bruin context layer documenting the
warehouse it builds. Use this guide before reading code or running queries.

## Canonical workflow

1. **Read context first.** Before querying, open the relevant
   `context/assets/<schema>/<table>.asset.yml`. It has the description, grain,
   column docs, and quality checks for that table - written from real samples.
2. **Use Bruin MCP for tooling questions.** Anything like "how does
   `bruin import` work?" or "what asset types exist?" - call the MCP server,
   don't guess from training data.
3. **Use `bruin query` for SQL.** Always pass `--config-file context/.bruin.yml`
   so the scoped connection is used.
4. **Cite the asset(s) you read.** When answering, reference the
   `context/assets/...asset.yml` files you used.

## Data access

- Connection name: `contoso_dbt_bq`
- Auth: Application Default Credentials (inherits `gcloud auth application-default login`)
- This is **read-only.** Never INSERT, UPDATE, DELETE, MERGE, or DROP.
- Always show the SQL before executing it.
- Use `LIMIT 100` (or smaller) when exploring an unfamiliar table.

## Layout

- `models/` - dbt models. Don't run `dbt` for analysis questions; the
  warehouse is already built. Read these only when asked about transformation logic.
- `context/assets/contoso_dbt_raw/` - raw dlt-loaded tables (lowest level).
- `context/assets/contoso_dbt_staging/` - `stg_*` cleaned/typed views.
- `context/assets/contoso_dbt_reports/` - `rpt_*` mart-level reports.
  Prefer these for business questions; staging is for ad-hoc deep dives.

## Things to avoid

- **Don't hand-edit `context/assets/*.asset.yml`.** They're regenerated by
  `generate_context.sh`. Improve descriptions in the dbt model's `schema.yml`
  upstream and re-run the generator.
- **Don't mix configs across pipelines.** This project's connection lives in
  `context/.bruin.yml`; other Bruin pipelines in the repo have their own.
  Always use `--config-file`.
- **Don't trust row counts in descriptions.** They're snapshot-time and may
  be stale. If a question hinges on exact size, run `SELECT COUNT(*)` yourself.

4. Try the loop end-to-end

Open your AI tool in this repo and ask a real question, e.g.:

"Which retail categories had the largest year-over-year revenue change in 2024 vs. 2023? Show me your SQL before running it, and cite which context/assets/... files you used."

A correctly-wired agent will:

Open context/assets/contoso_dbt_reports/rpt_revenue_by_segment.asset.yml and confirm the grain
Draft a SQL query against contoso_dbt_reports.rpt_revenue_by_segment filtered by year
Show the SQL, wait for a go-ahead, then run bruin query --config-file context/.bruin.yml --connection contoso_dbt_bq --query "..."
Cite the asset YAML it read

If it skips step 1 (reading the asset), tighten AGENTS.md - the canonical workflow section is what enforces this behavior.

dbt + Bruin AI Data Analyst