feat: add multi-project SQL and admin API tools by DevonFulcher · Pull Request #661 · dbt-labs/dbt-mcp

DevonFulcher · 2026-03-17T13:23:39Z

Why

Part of the multi-project feature (Phases 5 & 6). Adds project-aware SQL and admin API tools that accept project_id as a required parameter, enabling agents to work across multiple dbt projects.

What

SQL tools (Phase 5) - New local tool definitions that proxy to remote SQL tools with project-specific configuration:

text_to_sql_for_project(project_id, query) - Generates SQL from natural language using the specified project's production environment
execute_sql_for_project(project_id, sql_query, limit) - Executes SQL against the specified project's development environment

Both validate that the required environment exists and raise clear ValueError if not.

Admin API tools (Phase 6) - New tools that filter admin API results by project:

list_jobs_for_project(project_id, limit, offset) - Lists jobs filtered by project ID
list_jobs_runs_for_project(project_id, job_id, status, limit) - Lists job runs filtered by project ID

Infrastructure:

Added get_config_for_project() default method to ConfigProvider base class (raises NotImplementedError - concrete implementations come from Phase 1 PR feat: extract project/environment helpers for multi-project support #657)
New src/dbt_mcp/sql/ module for multi-project SQL tool definitions
Prompt files, tool name enum entries, toolset mappings, and README mappings for all 4 new tools

Notes

These tools are designed for Server B (multi-project mode) and are NOT registered in Server A
Depends on Phase 1 (feat: extract project/environment helpers for multi-project support #657) for get_config_for_project() concrete implementations on the config providers
Existing Server A tools are unchanged

Drafted by Claude Opus 4.6 under the direction of @DevonFulcher

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

This will be introduced in the first phase where it has non-empty content. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Remove get_config_for_project() from all config providers. Each multiproject semantic layer tool now calls _resolve_sl_config_for_project() which fetches credentials, builds the platform URL/headers, calls get_environments_for_project() directly, and returns the config via DefaultSemanticLayerConfigProvider._build_config(). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Add multi_project_only_toolsets set to toolsets.py and update generate_docs.py to skip those toolsets when generating README and diagram documentation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

diagram.d2 is already correct (multi-project toolset excluded). Restoring d2.png to match the unchanged diagram source. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

src/dbt_mcp/project/environment_resolver.py

…ools Multi-project server cannot run alongside single-project server, so tools share the same names (list_metrics, not list_metrics_for_project) and are controlled by the same env vars (DISABLE_SEMANTIC_LAYER). Remove MULTI_PROJECT_SEMANTIC_LAYER toolset, multi_project_only_toolsets, and multi_project_tools variables. Remove disable/enable_multi_project_semantic_layer settings fields. Remove multi_project_only_toolsets filtering from generate_docs.py. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…erConfigProvider Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…nticLayerFetcher Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add config_override parameter to all discovery client methods (MetadataAPIClient, PaginatedResourceFetcher, ModelsFetcher, ExposuresFetcher, SourcesFetcher, MacrosFetcher, ResourceDetailsFetcher, LineageFetcher, ModelPerformanceFetcher) to support per-call config overrides for multi-project mode. Create tools_multiproject.py with all 18 discovery tools mirroring Server A, each taking project_id as a required first parameter. Add get_config_for_project() to ConfigProvider ABC for multi-project config resolution. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Add config_override parameter to all discovery client methods (MetadataAPIClient, PaginatedResourceFetcher, ModelsFetcher, ExposuresFetcher, SourcesFetcher, MacrosFetcher, ResourceDetailsFetcher, LineageFetcher, ModelPerformanceFetcher) to support per-call config overrides for multi-project mode. Create tools_multiproject.py with all 18 discovery tools mirroring Server A, each taking project_id as a required first parameter. Add get_config_for_project() to ConfigProvider ABC for multi-project config resolution. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

… tools Multi-project server cannot run alongside single-project server, so tools share the same names (text_to_sql, not text_to_sql_for_project) and are controlled by the same env vars (DISABLE_SQL, DISABLE_ADMIN_API). Remove _FOR_PROJECT ToolName entries, remove from toolsets dict. Rename multi-project tool functions and MCP names to match single-project. Separate MULTIPROJECT_ADMIN_API_TOOLS from ADMIN_TOOLS. Add register_multiproject_admin_api_tools function. Remove unused _for_project prompt files. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

DevonFulcher requested a deployment to integration March 17, 2026 13:23 — with GitHub Actions Waiting

DevonFulcher requested a deployment to integration March 17, 2026 14:54 — with GitHub Actions Waiting

DevonFulcher requested a deployment to integration March 17, 2026 16:57 — with GitHub Actions Waiting

DevonFulcher and others added 12 commits March 17, 2026 12:52

feat: migrate requests to httpx async for project resolvers

4cf34e6

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat: extract project/environment helpers for multi-project support

35fa55d

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

feat: add server_b_toolsets exclusion mechanism for README generation

06dbf2a

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

refactor: rename server_b_toolsets to multi_project_only_toolsets

a4eecc5

refactor: remove unused multi_project_only_toolsets from phase 1

70b2a82

This will be introduced in the first phase where it has non-empty content. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat: add multi-project semantic layer tools

dcb214c

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix: apply ruff formatting and add pytest-of-* to .gitignore

f87250c

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

chore: regenerate docs/d2.png

311e7b1

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat: exclude multi-project tools from README

221f455

Add multi_project_only_toolsets set to toolsets.py and update generate_docs.py to skip those toolsets when generating README and diagram documentation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

refactor: move config building inline into tool resolver helper

595f2c9

fix: revert d2.png to match main (multi-project tools not in diagram)

1fe558d

diagram.d2 is already correct (multi-project toolset excluded). Restoring d2.png to match the unchanged diagram source. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

DevonFulcher force-pushed the df/multiproject-phase56-sql-admin branch from 8415707 to 37f8127 Compare March 17, 2026 18:14

DevonFulcher requested a deployment to integration March 17, 2026 18:15 — with GitHub Actions Waiting

github-advanced-security bot found potential problems Mar 17, 2026

View reviewed changes

src/dbt_mcp/project/environment_resolver.py Dismissed Show dismissed Hide dismissed

DevonFulcher force-pushed the df/multiproject-phase56-sql-admin branch from 37f8127 to 90165f8 Compare March 17, 2026 18:33

DevonFulcher requested a deployment to integration March 17, 2026 18:33 — with GitHub Actions Waiting

refactor: move _resolve_sl_config_for_project into DefaultSemanticLay…

1b22cc7

…erConfigProvider Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

DevonFulcher requested a deployment to integration March 18, 2026 14:08 — with GitHub Actions Waiting

DevonFulcher requested a deployment to integration March 18, 2026 14:10 — with GitHub Actions Waiting

fix: await get_environments_for_project and fix formatting

6605fdf

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

DevonFulcher force-pushed the df/multiproject-phase56-sql-admin branch from 00bf2a4 to a6796c2 Compare March 18, 2026 14:29

DevonFulcher requested a deployment to integration March 18, 2026 14:29 — with GitHub Actions Waiting

DevonFulcher and others added 3 commits March 18, 2026 09:46

refactor: remove config_override from SemanticLayerFetcher methods

287eba9

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

refactor: introduce ProjectSemanticLayerConfigProvider, simplify Sema…

928c19e

…nticLayerFetcher Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

DevonFulcher and others added 16 commits March 18, 2026 09:57

chore: add changelog entry

e6d9a4e

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix: apply ruff formatting and add pytest-of-* to .gitignore

1b7014e

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

refactor: resolve environments directly in tool functions

6f2869e

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

refactor: move config building inline into tool resolver helper

90fbf0a

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix: await get_environments_for_project in discovery tools

c33b58a

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

refactor: use _resolve_project_environments in discovery tools

d267b9e

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

refactor: resolve environments directly in tool functions

0d5c2c0

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat: add multi-project SQL and admin API tools

470732a

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix: apply ruff formatting and add pytest-of-* to .gitignore

2169c3b

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

refactor: resolve environments directly in tool functions

6963c22

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

feat: exclude multi-project tools from README

15d6cbb

fix: update admin tools test count to 12

969ddf8

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

fix: await get_environments_for_project in sql tools

c682e02

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

refactor: use _resolve_project_environments in sql tools

b3d5fe9

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

DevonFulcher force-pushed the df/multiproject-phase56-sql-admin branch from a6796c2 to b3d5fe9 Compare March 18, 2026 15:00

DevonFulcher requested a deployment to integration March 18, 2026 15:00 — with GitHub Actions Waiting

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add multi-project SQL and admin API tools#661

feat: add multi-project SQL and admin API tools#661
DevonFulcher wants to merge 34 commits intomainfrom
df/multiproject-phase56-sql-admin

DevonFulcher commented Mar 17, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

DevonFulcher commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What

Notes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

DevonFulcher commented Mar 17, 2026 •

edited

Loading