Rename Remote Tools to SQL Tools

Author: DevonFulcher

.changes/unreleased/Under the Hood-20250729-163233.yaml

@@ -0,0 +1,3 @@
+kind: Under the Hood
+body: Rename Remote Tools to SQL Tools
+time: 2025-07-29T16:32:33.198341-05:00

.task/checksum/d2

@@ -1 +1 @@
-31337af97fd86e997bc2f565c952abab
+783a7ad93470e77eac8085bb455e12e

README.md

@@ -37,7 +37,7 @@ This MCP (Model Context Protocol) server provides tools to interact with dbt. Re
 * `get_model_parents` - Gets parent nodes of a specific model
 * `get_model_children` - Gets children modes of a specific model
 
-### Remote
+### SQL
 * `text_to_sql` - Generate SQL from natural language requests
 * `execute_sql` - Execute SQL on dbt Cloud's backend infrastructure with support for Semantic Layer SQL syntax. Note: using a PAT instead of a service token for `DBT_TOKEN` is required for this tool.
 
@@ -50,25 +50,25 @@ This MCP (Model Context Protocol) server provides tools to interact with dbt. Re
 
 The MCP server takes the following environment variable configuration:
 
-### Tool Groups
+### Tools
 | Name                     | Default | Description                                                                     |
 | ------------------------ | ------- | ------------------------------------------------------------------------------- |
 | `DISABLE_DBT_CLI`        | `false` | Set this to `true` to disable dbt Core, dbt Cloud CLI, and dbt Fusion MCP tools |
-| `DISABLE_SEMANTIC_LAYER` | `false` | Set this to `true` to disable dbt Semantic Layer MCP objects                    |
-| `DISABLE_DISCOVERY`      | `false` | Set this to `true` to disable dbt Discovery API MCP objects                     |
-| `DISABLE_REMOTE`         | `true`  | Set this to `false` to enable remote MCP objects                                |
+| `DISABLE_SEMANTIC_LAYER` | `false` | Set this to `true` to disable dbt Semantic Layer MCP tools                    |
+| `DISABLE_DISCOVERY`      | `false` | Set this to `true` to disable dbt Discovery API MCP tools                     |
+| `DISABLE_SQL`         | `true`  | Set this to `false` to enable SQL MCP tools                                |
 | `DISABLE_TOOLS`          | ""      | Set this to a list of tool names delimited by a `,` to disable certain tools    |
 
 
-### Configuration for Discovery, Semantic Layer, and Remote Tools
+### Configuration for Discovery, Semantic Layer, and SQL Tools
 | Name                       | Default            | Description                                                                                                                                                                                                                                  |
 | -------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `DBT_HOST`                 | `cloud.getdbt.com` | Your dbt Cloud instance hostname. This will look like an `Access URL` found [here](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses). If you are using Multi-cell, do not include the `ACCOUNT_PREFIX` here        |
 | `MULTICELL_ACCOUNT_PREFIX` | -                  | If you are using Multi-cell, set this to your `ACCOUNT_PREFIX`. If you are not using Multi-cell, do not set this environment variable. You can learn more [here](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) |
 | `DBT_TOKEN`                | -                  | Your personal access token or service token. Note: a service token is required when using the Semantic Layer and this service token should have at least `Semantic Layer Only`, `Metadata Only`, and `Developer` permissions.                |
 | `DBT_PROD_ENV_ID`          | -                  | Your dbt Cloud production environment ID                                                                                                                                                                                                     |
 
-### Configuration for Remote Tools
+### Configuration for SQL Tools
 | Name             | Description                               |
 | ---------------- | ----------------------------------------- |
 | `DBT_DEV_ENV_ID` | Your dbt Cloud development environment ID |

docs/d2.png

@@ -52,7 +52,7 @@ tools: Tools {
     query_metrics
   }
 
-  remote: Remote tools {
+  sql: SQL tools {
     label.near: outside-right-center
     class: container
     text_to_sql

docs/diagram.d2

@@ -38,7 +38,7 @@ class DbtCliConfig(BaseModel):
     dbt_cli_timeout: int
 
 
-class RemoteConfig(BaseModel):
+class SqlConfig(BaseModel):
     multicell_account_prefix: str | None = None
     host: str
     user_id: int
@@ -72,7 +72,8 @@ class DbtMcpSettings(BaseSettings):
     disable_dbt_cli: bool = Field(False, alias="DISABLE_DBT_CLI")
     disable_semantic_layer: bool = Field(False, alias="DISABLE_SEMANTIC_LAYER")
     disable_discovery: bool = Field(False, alias="DISABLE_DISCOVERY")
-    disable_remote: bool = Field(True, alias="DISABLE_REMOTE")
+    disable_remote: bool | None = Field(None, alias="DISABLE_REMOTE")
+    disable_sql: bool | None = Field(None, alias="DISABLE_SQL")
     disable_tools: Annotated[list[ToolName] | None, NoDecode] = Field(
         None, alias="DISABLE_TOOLS"
     )
@@ -87,6 +88,14 @@ def actual_host(self) -> str | None:
     def actual_prod_environment_id(self) -> int | None:
         return self.dbt_prod_env_id or self.dbt_env_id
 
+    @property
+    def actual_disable_sql(self) -> bool:
+        if self.disable_sql is not None:
+            return self.disable_sql
+        if self.disable_remote is not None:
+            return self.disable_remote
+        return True
+
     @field_validator("disable_tools", mode="before")
     @classmethod
     def parse_disable_tools(cls, env_var: str | None) -> list[ToolName]:
@@ -112,7 +121,7 @@ def parse_disable_tools(cls, env_var: str | None) -> list[ToolName]:
 
 class Config(BaseModel):
     tracking_config: TrackingConfig
-    remote_config: RemoteConfig | None = None
+    sql_config: SqlConfig | None = None
     dbt_cli_config: DbtCliConfig | None = None
     discovery_config: DiscoveryConfig | None = None
     semantic_layer_config: SemanticLayerConfig | None = None
@@ -133,19 +142,19 @@ def load_config() -> Config:
     if (
         not settings.disable_semantic_layer
         or not settings.disable_discovery
-        or not settings.disable_remote
+        or not settings.actual_disable_sql
     ):
         if not settings.actual_host:
             errors.append(
-                "DBT_HOST environment variable is required when semantic layer, discovery, or remote tools are enabled."
+                "DBT_HOST environment variable is required when semantic layer, discovery, or SQL tools are enabled."
             )
         if not settings.actual_prod_environment_id:
             errors.append(
-                "DBT_PROD_ENV_ID environment variable is required when semantic layer, discovery, or remote tools are enabled."
+                "DBT_PROD_ENV_ID environment variable is required when semantic layer, discovery, or SQL tools are enabled."
             )
         if not settings.dbt_token:
             errors.append(
-                "DBT_TOKEN environment variable is required when semantic layer, discovery, or remote tools are enabled."
+                "DBT_TOKEN environment variable is required when semantic layer, discovery, or SQL tools are enabled."
             )
         if settings.actual_host and (
             settings.actual_host.startswith("metadata")
@@ -154,14 +163,14 @@ def load_config() -> Config:
             errors.append(
                 "DBT_HOST must not start with 'metadata' or 'semantic-layer'."
             )
-    if not settings.disable_remote:
+    if not settings.actual_disable_sql:
         if not settings.dbt_dev_env_id:
             errors.append(
-                "DBT_DEV_ENV_ID environment variable is required when remote tools are enabled."
+                "DBT_DEV_ENV_ID environment variable is required when SQL tools are enabled."
             )
         if not settings.dbt_user_id:
             errors.append(
-                "DBT_USER_ID environment variable is required when remote tools are enabled."
+                "DBT_USER_ID environment variable is required when SQL tools are enabled."
             )
     if not settings.disable_dbt_cli:
         if not settings.dbt_project_dir:
@@ -177,16 +186,16 @@ def load_config() -> Config:
         raise ValueError("Errors found in configuration:\n\n" + "\n".join(errors))
 
     # Build configurations
-    remote_config = None
+    sql_config = None
     if (
-        not settings.disable_remote
+        not settings.actual_disable_sql
         and settings.dbt_user_id
         and settings.dbt_token
         and settings.dbt_dev_env_id
         and settings.actual_prod_environment_id
         and settings.actual_host
     ):
-        remote_config = RemoteConfig(
+        sql_config = SqlConfig(
             multicell_account_prefix=settings.multicell_account_prefix,
             user_id=settings.dbt_user_id,
             token=settings.dbt_token,
@@ -270,7 +279,7 @@ def load_config() -> Config:
             dbt_cloud_user_id=settings.dbt_user_id,
             local_user_id=local_user_id,
         ),
-        remote_config=remote_config,
+        sql_config=sql_config,
         dbt_cli_config=dbt_cli_config,
         discovery_config=discovery_config,
         semantic_layer_config=semantic_layer_config,

src/dbt_mcp/config/config.py

@@ -16,8 +16,8 @@
 from dbt_mcp.config.config import Config
 from dbt_mcp.dbt_cli.tools import register_dbt_cli_tools
 from dbt_mcp.discovery.tools import register_discovery_tools
-from dbt_mcp.remote.tools import register_remote_tools
 from dbt_mcp.semantic_layer.tools import register_sl_tools
+from dbt_mcp.sql.tools import register_sql_tools
 from dbt_mcp.tracking.tracking import UsageTracker
 
 logger = logging.getLogger(__name__)
@@ -112,8 +112,8 @@ async def create_dbt_mcp(config: Config):
         logger.info("Registering dbt cli tools")
         register_dbt_cli_tools(dbt_mcp, config.dbt_cli_config, config.disable_tools)
 
-    if config.remote_config:
-        logger.info("Registering remote tools")
-        await register_remote_tools(dbt_mcp, config.remote_config, config.disable_tools)
+    if config.sql_config:
+        logger.info("Registering SQL tools")
+        await register_sql_tools(dbt_mcp, config.sql_config, config.disable_tools)
 
     return dbt_mcp

src/dbt_mcp/mcp/server.py

@@ -8,7 +8,7 @@
 from httpx import Client
 from mcp import CallToolRequest, JSONRPCResponse, ListToolsResult
 from mcp.server.fastmcp import FastMCP
-from mcp.server.fastmcp.tools.base import Tool
+from mcp.server.fastmcp.tools.base import Tool as InternalTool
 from mcp.server.fastmcp.utilities.func_metadata import (
     ArgModelBase,
     FuncMetadata,
@@ -19,20 +19,20 @@
     CallToolResult,
     ContentBlock,
     TextContent,
+    Tool,
 )
-from mcp.types import Tool as RemoteTool
 from pydantic import Field, ValidationError, WithJsonSchema, create_model
 from pydantic.fields import FieldInfo
 from pydantic_core import PydanticUndefined
 
-from dbt_mcp.config.config import RemoteConfig
+from dbt_mcp.config.config import SqlConfig
 from dbt_mcp.tools.tool_names import ToolName
 
 logger = logging.getLogger(__name__)
 
 
 # Based on this: https://github.com/modelcontextprotocol/python-sdk/blob/9ae4df85fbab97bf476ddd160b766ca4c208cd13/src/mcp/server/fastmcp/utilities/func_metadata.py#L105
-def get_remote_tool_fn_metadata(tool: RemoteTool) -> FuncMetadata:
+def get_remote_tool_fn_metadata(tool: Tool) -> FuncMetadata:
     dynamic_pydantic_model_params: dict[str, Any] = {}
     for key in tool.inputSchema["properties"].keys():
         # Remote tools shouldn't have type annotations or default values
@@ -58,23 +58,29 @@ def get_remote_tool_fn_metadata(tool: RemoteTool) -> FuncMetadata:
     )
 
 
-def _get_remote_tools(base_url: str, headers: dict[str, str]) -> list[RemoteTool]:
+def _get_sql_tools(base_url: str, headers: dict[str, str]) -> list[Tool]:
     try:
         with Client(base_url=base_url, headers=headers) as client:
             list_tools_response = JSONRPCResponse.model_validate_json(
                 client.get("/tools/list").text
             )
             return ListToolsResult.model_validate(list_tools_response.result).tools
     except Exception as e:
-        logger.error(f"Error getting remote tools: {e}")
+        logger.error(f"Error getting SQL tools: {e}")
         return []
 
 
-async def register_remote_tools(
+async def register_sql_tools(
     dbt_mcp: FastMCP,
-    config: RemoteConfig,
+    config: SqlConfig,
     exclude_tools: Sequence[ToolName] = [],
 ) -> None:
+    """
+    Register SQL MCP tools.
+
+    SQL tools are hosted remotely, so their definitions aren't found in this repo.
+    """
+
     is_local = config.host and config.host.startswith("localhost")
     path = "/mcp" if is_local else "/api/ai/mcp"
     scheme = "http://" if is_local else "https://"
@@ -88,11 +94,11 @@ async def register_remote_tools(
         "x-dbt-dev-environment-id": str(config.dev_environment_id),
         "x-dbt-user-id": str(config.user_id),
     }
-    remote_tools = _get_remote_tools(base_url=base_url, headers=headers)
+    sql_tools = _get_sql_tools(base_url=base_url, headers=headers)
     logger.info(
-        f"Loaded remote tools: {', '.join([tool.name for tool in remote_tools])}",
+        f"Loaded sql tools: {', '.join([tool.name for tool in sql_tools])}",
     )
-    for tool in remote_tools:
+    for tool in sql_tools:
         if tool.name.lower() in [tool.value.lower() for tool in exclude_tools]:
             continue
 
@@ -151,7 +157,7 @@ async def tool_function(*args, **kwargs) -> Sequence[ContentBlock]:
             return tool_function
 
         new_tool = create_tool_function(tool.name)
-        dbt_mcp._tool_manager._tools[tool.name] = Tool(
+        dbt_mcp._tool_manager._tools[tool.name] = InternalTool(
             fn=new_tool,
             title=tool.title,
             name=tool.name,

src/dbt_mcp/remote/tools.py src/dbt_mcp/sql/tools.pysrc/dbt_mcp/remote/tools.py renamed to src/dbt_mcp/sql/tools.py

@@ -32,7 +32,7 @@ class ToolName(Enum):
     GET_MODEL_PARENTS = "get_model_parents"
     GET_MODEL_CHILDREN = "get_model_children"
 
-    # Remote tools
+    # SQL tools
     TEXT_TO_SQL = "text_to_sql"
     EXECUTE_SQL = "execute_sql"
 

src/dbt_mcp/tools/tool_names.py

@@ -1,24 +1,24 @@
 from mcp.server.fastmcp import FastMCP
 
 from dbt_mcp.config.config import load_config
-from dbt_mcp.remote.tools import register_remote_tools
+from dbt_mcp.sql.tools import register_sql_tools
 
 
-async def test_remote_tool_execute_sql():
+async def test_sql_tool_execute_sql():
     config = load_config()
     dbt_mcp = FastMCP("Test")
-    await register_remote_tools(dbt_mcp, config.remote_config)
+    await register_sql_tools(dbt_mcp, config.sql_config)
     tools = await dbt_mcp.list_tools()
     print(tools)
     result = await dbt_mcp.call_tool("execute_sql", {"sql": "SELECT 1"})
     assert len(result) == 1
     assert "1" in result[0].text
 
 
-async def test_remote_tool_text_to_sql():
+async def test_sql_tool_text_to_sql():
     config = load_config()
     dbt_mcp = FastMCP("Test")
-    await register_remote_tools(dbt_mcp, config.remote_config)
+    await register_sql_tools(dbt_mcp, config.sql_config)
     result = await dbt_mcp.call_tool("text_to_sql", {"text": "SELECT 1"})
     assert len(result) == 1
     assert "SELECT 1" in result[0].text