---
name: dbt-docs-search
description: Search across Gemma's dbt client projects using the deployed MCP server. Provides semantic + keyword search over 29+ client dbt projects. Requires Gemma Firezone VPN and the gemma-dbt-docs MCP server (installed automatically with this plugin).
---

# dbt Docs Search

The `gemma-dbt-docs` MCP server gives you semantic search over all Gemma client dbt
projects — useful for reusing SQL patterns, understanding how a specific technique was
implemented, or exploring what a client's data model looks like.

**Requires:** Gemma Firezone VPN. The server is at `https://dbt-docs.gemmaanalytics.com/mcp`.

## Available MCP tools

### `search_dbt_models`

Search for SQL patterns, techniques, or model descriptions across all ingested dbt projects.

**Use when the user asks:**
- "How did we implement incremental loads for a client?"
- "Find SCD type 2 examples"
- "Show me sessionization logic from past projects"
- "How is the orders model built in [client]?"
- "Find all models that use a surrogate key"

**Example invocations:**
```
search_dbt_models(query="incremental strategy for events table")
search_dbt_models(query="customer lifetime value calculation", project="acme", limit=5)
search_dbt_models(query="SCD type 2 dimension", limit=10)
```

### `list_dbt_projects`

List all available projects (clients) or explore models within a specific project.

**Use when the user asks:**
- "What dbt projects are in the knowledge base?"
- "What does the [client] project look like?"
- "How many models does [client] have?"

**Example invocations:**
```
list_dbt_projects()
list_dbt_projects(project="juit")
```

## Workflow tips

- Start with `list_dbt_projects()` if you're not sure which client has the pattern you need
- Use `search_dbt_models` with specific technical terms (CTE names, column types, dbt macros)
  for best precision
- Combine with the `create-base-models` and `create-source-file` skills when scaffolding
  new models: search for how similar models were built, then scaffold from that pattern
- Search results include the SQL chunk, model name, project name, and a relevance hint —
  use the hint to explain which result to look at first

## Troubleshooting

| Issue | Fix |
|-------|-----|
| Tools not available in Claude Code | Reconnect VPN; restart Claude Code to reload MCP |
| "Connection refused" or timeout | Confirm VPN: `ping 18.195.8.150` should respond |
| Empty results for a known project | Index may need updating — ask someone with access to run `make upload-index` from `gemma-dbt-docs-mcp` |
| Slow first query (~30 s) | Server ONNX model warming up — normal on fresh deploy |