Improve Your Context

Why this step matters

By now your AI analyst works — it knows your schema, understands your domain terms, and can query your warehouse. But there's a ceiling. The context it relies on is limited to what's in your AGENTS.md and your asset files. Your organization almost certainly has richer knowledge sitting elsewhere: internal wikis, product specs, data dictionaries maintained by other teams, and business rules documented in Notion or Confluence.

This step shows you two ways to push past that ceiling:

Bruin Glossary — a structured, version-controlled dictionary of business entities and their attributes that Bruin uses to keep column definitions consistent across assets
External MCP servers — connect your AI tool to Notion or Confluence so the agent can pull context directly from your team's existing documentation

Neither is required. Your analyst already works without them. But both make it significantly better at understanding the nuances of your business.

Option A: Create a Bruin Glossary

The glossary solves a specific problem: the same concept (e.g. "Customer") means different things to different teams. A CRM manager calls everyone on the email list a customer. A backend engineer says a customer is a row in the customers table. A product manager says a customer is someone who's made at least one purchase.

When your AI agent reads five different asset files that each define customer_id slightly differently, it doesn't know which one to trust. The glossary gives it a single source of truth.

How it works

Create a glossary.yml file at the root of your Bruin project. This file defines entities (high-level business concepts) and their attributes (the logical fields of that entity). You can also group entities into domains for organizational clarity.

domains:
  customer-management:
    description: Customer data, registration, and account management
    owners:
      - "Customer Success Team"
    contact:
      - type: "slack"
        address: "#customer-success"

entities:
  Customer:
    description: An individual or business that has completed at least one purchase.
    domains:
      - customer-management
    attributes:
      ID:
        type: integer
        description: Unique identifier for the customer in our systems.
      Email:
        type: string
        description: Email address used during registration.
      Language:
        type: string
        description: Language the customer selected during sign-up.

  Order:
    description: A completed transaction with one or more line items.
    domains:
      - customer-management
    attributes:
      ID:
        type: integer
        description: Unique identifier for the order.
      Status:
        type: string
        description: "Current fulfillment state: pending, shipped, delivered, or refunded."
      Total:
        type: decimal
        description: Net order total in USD after discounts, before tax.

Linking glossary entities to assets

Once the glossary exists, reference it from your asset files using extends. This keeps definitions consistent without duplicating text:

name: raw.customers

columns:
  - name: customer_id
    extends: Customer.ID
  - name: email
    extends: Customer.Email

Bruin merges the glossary definition into the column — if the column already has a description, the column's version wins. The glossary fills in whatever is missing.

You can also extend an entire entity at the asset level to pull in all its attributes at once:

name: raw.customers
extends:
  - Customer

Why this matters for your AI analyst

The glossary doesn't just help Bruin — it helps the AI agent. When the agent reads asset files that extend glossary entities, it sees consistent, authoritative definitions everywhere. Instead of guessing whether cust_id and customer_id mean the same thing, it can follow the glossary trail back to a single Customer.ID definition.

Option B: Connect external documentation via MCP

Your team's knowledge doesn't all live in YAML files. Product requirements, data dictionaries, business rules, onboarding docs — most of it lives in Notion or Confluence. You can give your AI agent direct access to that knowledge by adding more MCP servers alongside Bruin.

Notion MCP

If your team uses Notion, the Notion MCP server lets your AI tool search across your workspace, read pages, and pull context in real time.

Setting up in Cursor:

Add this to your MCP configuration:

{
  "mcpServers": {
    "bruin": {
      "command": "bruin",
      "args": ["mcp"]
    },
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer <your-notion-api-key>\",\"Notion-Version\":\"2022-06-28\"}"
      }
    }
  }
}

Setting up in Claude Code:

claude mcp add notion -- npx -y @notionhq/notion-mcp-server

Then set the OPENAPI_MCP_HEADERS environment variable with your Notion API key.

Once connected, you can tell the agent in your AGENTS.md:

## External context
- You have access to Notion via MCP. Before answering domain-specific questions,
  search Notion for relevant product specs, data dictionaries, or business rules.
- Prefer Notion definitions over assumptions when terms are ambiguous.

Confluence MCP (Atlassian Rovo)

If your team uses Confluence, the Atlassian Rovo MCP Server provides similar capabilities — search, read, and pull context from Confluence pages and Jira issues.

Setting up in Cursor or Claude Code:

The Atlassian MCP server uses OAuth for authentication. Add it as a remote MCP server:

{
  "mcpServers": {
    "bruin": {
      "command": "bruin",
      "args": ["mcp"]
    },
    "atlassian": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/mcp"]
    }
  }
}

On first connection, a browser window will open for OAuth authorization. After that, the agent can search and read Confluence pages directly.

Add a note to your AGENTS.md:

## External context
- You have access to Confluence via MCP. Search for data dictionaries,
  business rule documentation, and metric definitions before writing queries.
- Cross-reference Confluence definitions with the glossary when available.

Combining both approaches

The glossary and external MCP servers complement each other well:

Glossary handles the structured, version-controlled definitions that Bruin uses directly — entity names, attribute types, column mappings
Notion / Confluence provides the unstructured context that doesn't fit in YAML — product specs, business logic explanations, historical decision records

For the best results, use the glossary for anything the AI needs to map to actual database columns, and point to Notion/Confluence for the "why" behind business rules and data structures.

What just happened

You've extended your AI analyst's knowledge beyond schema files. With a glossary, it has a single source of truth for business concepts. With Notion or Confluence MCP, it can tap into your team's existing documentation on the fly. The more context the agent has, the better its queries — and the less time you spend correcting it.

Improve Your Context

Learn more