Semantic Layer / execute_sql tools fail with unhelpful error when dbt platform's Snowflake credentials expire
- 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
Assessment
This issue has not been assessed yet.