Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 25 additions & 11 deletions docs/5-data-diffing/mcp-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Recce compares your current branch's dbt models against a baseline from your mai

## Prerequisites

Before starting the MCP server, generate both artifact sets.
Before starting the MCP server, generate your development artifacts. Base artifacts are recommended for full diffing but not required.

### Generate development artifacts

Expand All @@ -61,8 +61,8 @@ git stash pop # restore changes

This creates `target-base/manifest.json` and `target-base/catalog.json`. The MCP server compares these two artifact sets to produce diffs.

!!! warning
The MCP server will not start if either `target/manifest.json` or `target-base/manifest.json` is missing.
!!! note
If `target-base/` is missing, the MCP server starts in **single-environment mode** — all tools remain available, but diff results show no changes because both sides reference the same data. Generate base artifacts to enable real comparisons.

## Installation

Expand Down Expand Up @@ -207,27 +207,41 @@ When connected, the MCP server exposes these tools to your AI agent:
| `schema_diff` | Detect schema changes (added, removed, or modified columns and type changes) |
| `row_count_diff` | Compare row counts between branches |
| `profile_diff` | Statistical profiling comparison (min, max, avg, nulls, and more) |
| `value_diff` | Compare actual data values between branches |
| `top_k_diff` | Compare top-K value distributions |
| `histogram_diff` | Compare value distributions as histograms |
| `query` | Run arbitrary SQL against your warehouse |
| `query_diff` | Run the same SQL against both branches and compare results |
| `list_checks` | List all validation checks in the current session with their status |
| `run_check` | Run a specific validation check by ID |

### Check types available through `run_check`

These check types are accessible as preset checks configured in `recce.yml` or created in the Recce instance. Your AI agent runs them with the `run_check` tool:

| Check type | Description |
|------------|-------------|
| `value_diff` | Compare actual data values row by row between branches |
| `top_k_diff` | Compare top-K value distributions |
| `histogram_diff` | Compare value distributions as histograms |

See [Preset checks](../7-cicd/preset-checks.md) for how to configure these check types.

!!! note
If base artifacts (`target-base/`) are not present, the server starts in **single-environment mode** — all tools remain available, but diff results show no changes. Generate base artifacts to enable real comparisons.

## Troubleshooting

### MCP server fails to start

The most common cause is missing dbt artifacts. Check that both artifact directories exist:
The most common cause is missing dbt artifacts. Check that your dbt artifacts exist:

```shell
ls target/manifest.json target-base/manifest.json
ls target/manifest.json
```

If either file is missing, follow the [Prerequisites](#prerequisites) section above.
If missing, run `dbt docs generate` in your current branch. See [Prerequisites](#prerequisites).

### "No such file or directory: target-base/manifest.json"
### Diff results show no changes

You need to generate base artifacts. See [Prerequisites](#prerequisites).
If the server starts but all diffs return empty results, you are likely in single-environment mode (missing base artifacts). Follow the [Generate base artifacts](#generate-base-artifacts) steps to enable real comparisons.

### Port already in use (SSE mode)

Expand Down