feat: add MCP elicitation for interactive DBT_HOST configuration (#728)

## Summary

Add MCP elicitation support so users can configure `DBT_HOST`
interactively when it's not set, instead of getting an error.

## What Changed

- New `elicitation.py` with reusable elicitation infrastructure
(`get_elicitation_session`, `elicit_or_raise`) that any future
elicitation can build on
- First consumer: `ElicitingCredentialsProvider` wraps
`CredentialsProvider` to prompt for `DBT_HOST` when missing, then feeds
it into the existing OAuth flow
- Elicited host persists to `~/.dbt/mcp.yml` via
`DbtPlatformContext.dbt_host` — reuses the existing context file and
`override()` merge logic (no separate config file)
- `config.py`/`settings.py`/`server.py`: wire the wrapper, stop
auto-disabling platform features, remove conditional guards on tool
registration

## Why

Users currently need to edit JSON config files to set `DBT_HOST` before
the server works. For non-technical users, this is a barrier. With
elicitation, the server prompts for the host interactively on first use,
persists it, and never asks again.

Clients that don't support elicitation (e.g., Claude Desktop) get the
original error message — no regression.

## Related Issues

Closes #488

### Testing 

###  MCP INSPECTOR:
<img width="1847" height="885" alt="image"
src="https://github.com/user-attachments/assets/383299a8-6f38-40a0-be70-8f48e82576ba"
/>
<img width="1847" height="885" alt="image"
src="https://github.com/user-attachments/assets/a7346cb9-8663-46da-bc09-85deb32263d2"
/>
<img width="1847" height="885" alt="image"
src="https://github.com/user-attachments/assets/4fbfe937-e928-4cba-9425-a237abe3c573"
/>


### CC
<img width="1331" height="211" alt="image"
src="https://github.com/user-attachments/assets/d87c72fd-874f-436d-983a-486e4f71b76a"
/>

<img width="1331" height="258" alt="image"
src="https://github.com/user-attachments/assets/bca12012-f756-494f-9d24-1a4c00aa5580"
/>
<img width="1331" height="258" alt="image"
src="https://github.com/user-attachments/assets/dd6ce39a-3372-4c50-a38a-fd31a4d4c54a"
/>




## Checklist
- [x] I have performed a self-review of my code
- [x] I have made corresponding changes to the documentation (in
https://github.com/dbt-labs/docs.getdbt.com) if required ->
dbt-labs/docs.getdbt.com#9001
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes

## Additional Notes

- Tested with MCP Inspector (elicitation form works), Claude Code
(elicitation works inline), and Claude Desktop (graceful degradation —
`elicitation=None` in capabilities)
- Only `DBT_HOST` is elicited; `DBT_PROJECT_DIR` and `DBT_PATH` remain
env-var-only for CLI users
- Elicited host persists to `~/.dbt/mcp.yml` as `dbt_host` field on
`DbtPlatformContext`; env vars always take precedence
- `host_prefix` is also restored from persisted context on restart for
multi-cell account URL construction

---------

Co-authored-by: Jairus Martinez <114552516+jairus-m@users.noreply.github.com>

Author: Muizzkolapo

.changes/unreleased/Enhancement or New Feature-20260417-232537.yaml

@@ -0,0 +1,3 @@
+kind: Enhancement or New Feature
+body: Elicit DBT_HOST from user on first platform tool call when not set via env vars (#488)
+time: 2026-04-17T23:25:37.853311+01:00

src/dbt_mcp/config/config.py

@@ -14,6 +14,7 @@
     MultiProjectSemanticLayerConfigProvider,
 )
 from dbt_mcp.config.credentials import CredentialsProvider
+from dbt_mcp.config.elicitation import ElicitingCredentialsProvider
 from dbt_mcp.config.settings import (
     DbtMcpLogSettings,
     DbtMcpSettings,
@@ -87,14 +88,14 @@ class Config:
     proxied_tool_config_provider: DefaultProxiedToolConfigProvider | None
     dbt_cli_config: DbtCliConfig | None
     dbt_codegen_config: DbtCodegenConfig | None
-    multi_project_discovery_config_provider: MultiProjectDiscoveryConfigProvider | None
-    discovery_config_provider: DefaultDiscoveryConfigProvider | None
+    multi_project_discovery_config_provider: MultiProjectDiscoveryConfigProvider
+    discovery_config_provider: DefaultDiscoveryConfigProvider
     multi_project_semantic_layer_config_provider: (
-        MultiProjectSemanticLayerConfigProvider | None
+        MultiProjectSemanticLayerConfigProvider
     )
-    semantic_layer_config_provider: DefaultSemanticLayerConfigProvider | None
-    admin_api_config_provider: DefaultAdminApiConfigProvider | None
-    credentials_provider: CredentialsProvider
+    semantic_layer_config_provider: DefaultSemanticLayerConfigProvider
+    admin_api_config_provider: DefaultAdminApiConfigProvider
+    credentials_provider: ElicitingCredentialsProvider
     lsp_config: LspConfig | None
 
 
@@ -104,7 +105,9 @@ def load_config(enable_proxied_tools: bool = True) -> Config:
         file_logging=log_settings.file_logging, log_level=log_settings.log_level
     )
     settings = DbtMcpSettings()  # type: ignore
-    credentials_provider = CredentialsProvider(settings)
+
+    inner_credentials = CredentialsProvider(settings)
+    credentials_provider = ElicitingCredentialsProvider(inner_credentials)
 
     # Set default warn error options if not provided
     if settings.dbt_warn_error_options is None:
@@ -124,33 +127,39 @@ def load_config(enable_proxied_tools: bool = True) -> Config:
         if getattr(settings, attr_name, False)
     }
 
+    # Proxied tools still gated on explicit opt-in flag
     proxied_tool_config_provider = None
-    if enable_proxied_tools and settings.actual_host:
+    if enable_proxied_tools:
         proxied_tool_config_provider = DefaultProxiedToolConfigProvider(
-            credentials_provider=credentials_provider
+            credentials_provider=inner_credentials
         )
 
-    admin_api_config_provider = None
-    multi_project_discovery_config_provider = None
-    multi_project_semantic_layer_config_provider = None
-    if settings.actual_host:
-        admin_api_config_provider = DefaultAdminApiConfigProvider(
-            credentials_provider=credentials_provider,
-        )
-        admin_client = DbtAdminAPIClient(admin_api_config_provider)
-        multi_project_discovery_config_provider = MultiProjectDiscoveryConfigProvider(
-            credentials_provider=credentials_provider,
+    admin_api_config_provider = DefaultAdminApiConfigProvider(
+        credentials_provider=inner_credentials,
+    )
+    admin_client = DbtAdminAPIClient(admin_api_config_provider)
+    multi_project_discovery_config_provider = MultiProjectDiscoveryConfigProvider(
+        credentials_provider=inner_credentials,
+        admin_client=admin_client,
+    )
+    multi_project_semantic_layer_config_provider = (
+        MultiProjectSemanticLayerConfigProvider(
+            credentials_provider=inner_credentials,
             admin_client=admin_client,
+            metrics_related_max=settings.sl_metrics_related_max,
+            max_response_chars=settings.sl_metrics_max_response_chars,
         )
-        multi_project_semantic_layer_config_provider = (
-            MultiProjectSemanticLayerConfigProvider(
-                credentials_provider=credentials_provider,
-                admin_client=admin_client,
-                metrics_related_max=settings.sl_metrics_related_max,
-                max_response_chars=settings.sl_metrics_max_response_chars,
-            )
-        )
+    )
+    discovery_config_provider = DefaultDiscoveryConfigProvider(
+        credentials_provider=inner_credentials,
+    )
+    semantic_layer_config_provider = DefaultSemanticLayerConfigProvider(
+        credentials_provider=inner_credentials,
+        metrics_related_max=settings.sl_metrics_related_max,
+        max_response_chars=settings.sl_metrics_max_response_chars,
+    )
 
+    # CLI/codegen/LSP — still conditional (need concrete paths at registration time)
     dbt_cli_config = None
     if settings.dbt_project_dir and settings.dbt_path:
         binary_type = detect_binary_type(settings.dbt_path)
@@ -171,20 +180,6 @@ def load_config(enable_proxied_tools: bool = True) -> Config:
             binary_type=binary_type,
         )
 
-    discovery_config_provider = None
-    if settings.actual_host:
-        discovery_config_provider = DefaultDiscoveryConfigProvider(
-            credentials_provider=credentials_provider,
-        )
-
-    semantic_layer_config_provider = None
-    if settings.actual_host:
-        semantic_layer_config_provider = DefaultSemanticLayerConfigProvider(
-            credentials_provider=credentials_provider,
-            metrics_related_max=settings.sl_metrics_related_max,
-            max_response_chars=settings.sl_metrics_max_response_chars,
-        )
-
     lsp_config = None
     if settings.dbt_project_dir:
         lsp_binary_info = dbt_lsp_binary_info(

src/dbt_mcp/config/credentials.py

@@ -8,6 +8,7 @@
 from filelock import FileLock
 
 from dbt_mcp.config.config_providers.admin_api import DefaultAdminApiConfigProvider
+from dbt_mcp.errors.common import MissingHostError
 from dbt_mcp.config.headers import TokenProvider
 from dbt_mcp.config.settings import (
     DbtMcpSettings,
@@ -184,7 +185,7 @@ async def get_dbt_platform_context(
 
 
 class CredentialsProvider:
-    def __init__(self, settings: "DbtMcpSettings") -> None:
+    def __init__(self, settings: DbtMcpSettings) -> None:
         self.settings = settings
         self.token_provider: TokenProvider | None = None
         self.authentication_method: AuthenticationMethod | None = None
@@ -231,7 +232,7 @@ def _log_settings(self) -> None:
             settings["dbt_token"] = "***redacted***"
         logger.info(f"Settings: {settings}")
 
-    async def get_credentials(self) -> "tuple[DbtMcpSettings, TokenProvider]":
+    async def get_credentials(self) -> tuple[DbtMcpSettings, TokenProvider]:
         if self.token_provider is not None:
             # If token provider is already set, just return the cached values
             return self.settings, self.token_provider
@@ -248,13 +249,22 @@ async def get_credentials(self) -> "tuple[DbtMcpSettings, TokenProvider]":
                 dbt_profiles_dir=self.settings.dbt_profiles_dir
             )
             config_location = dbt_user_dir / "mcp.yml"
+            dbt_platform_context_manager = DbtPlatformContextManager(config_location)
+            existing_context = dbt_platform_context_manager.read_context()
+            if existing_context and not self.settings.actual_host:
+                if existing_context.dbt_host:
+                    self.settings.dbt_host = existing_context.dbt_host
+                if (
+                    existing_context.host_prefix
+                    and not self.settings.actual_host_prefix
+                ):
+                    self.settings.host_prefix = existing_context.host_prefix
             actual_host = self.settings.actual_host
             if not actual_host:
-                raise ValueError("DBT_HOST is a required environment variable")
+                raise MissingHostError("DBT_HOST is a required environment variable")
             dbt_platform_url = _build_dbt_platform_url(
                 actual_host, self.settings.actual_host_prefix
             )
-            dbt_platform_context_manager = DbtPlatformContextManager(config_location)
             dbt_platform_context = await get_dbt_platform_context(
                 dbt_platform_context_manager=dbt_platform_context_manager,
                 dbt_user_dir=dbt_user_dir,
@@ -277,6 +287,9 @@ async def get_credentials(self) -> "tuple[DbtMcpSettings, TokenProvider]":
             self.settings.host_prefix = dbt_platform_context.host_prefix
             self.settings.dbt_project_ids = dbt_platform_context.selected_project_ids
             self.settings.dbt_host = self.settings.base_host
+            if isinstance(dbt_platform_context, DbtPlatformContext):
+                dbt_platform_context.dbt_host = self.settings.actual_host
+                dbt_platform_context_manager.write_context_to_file(dbt_platform_context)
             if not dbt_platform_context.decoded_access_token:
                 raise ValueError("No decoded access token found in OAuth context")