dbt-labs / dbt-labs/dbt-mcp

Semantic Layer / execute_sql tools fail with unhelpful error when dbt platform's Snowflake credentials expire

Open
#670 3 comments 1 reaction 0 assignees View on GitHub
Dominant language
Python
Stars
603
Forks
131
Avg merge
4h 26m
Merged PRs (30d)
18

Description

## Summary

When using MCP tools that execute queries against the warehouse **via the dbt platform** (i.e. `query_metrics` and `execute_sql`), if the platform's Snowflake credentials have expired, the tool returns a cryptic error message like:

```
SSO authentication has expired, please re-connect to Snowflake: https://docs.getdbt.com/faqs/Troubleshooting/refresh-snowflake-oauth-credentials
```

This error message is misleading and sends users down the wrong troubleshooting path.

## Two distinct auth scenarios

It's important to distinguish between two different authentication failure modes in dbt-mcp:

### 1. Local machine → Snowflake (dbt CLI tools)
Applies to tools that run dbt commands locally (`build`, `run`, `show`, etc.). Authentication is between the **local machine and Snowflake** — typically browser-based SSO (`externalbrowser`). Already tracked in #628.

**Resolution:** Re-authenticate locally (e.g. run `dbt debug` to trigger a browser login).

### 2. dbt platform → Snowflake (warehouse-executing platform tools)
Applies to tools that send queries to the warehouse **through the dbt platform**: `query_metrics` and `execute_sql`. The local machine is not involved — the MCP server forwards the query to the dbt platform, which executes it against Snowflake using its own stored development credentials.

**Resolution:** The user must go to the **dbt Cloud UI → Profile → Credentials** and refresh their development environment credentials for the relevant project/environment. There is nothing to fix locally.

## Problem

The current error message points users toward local Snowflake reconnection steps (re-authenticate in the browser), which does not resolve the issue when the problem is actually expired credentials on the dbt platform side.

## Expected behavior

When `query_metrics` or `execute_sql` fail due to expired platform credentials, the error should:
1. Clearly indicate this is a **dbt platform credential expiry**, not a local auth issue
2. Direct the user to refresh their **development credentials in the dbt Cloud UI**

## Steps to reproduce

1. Configure dbt-mcp with Semantic Layer or SQL tools enabled
2. Let the dbt platform's Snowflake development credentials expire (or set up a fresh environment where they haven't been configured)
3. Call `query_metrics` or `execute_sql`
4. Observe the misleading error message

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.