Add support for Python debugger (#391)

## Summary
Adds Python debugger support by implementing `streamable-http` transport
alongside the default `stdio` transport.

- Maintains the behavior of being able to use `task inspector` command
to test tools via the MCP Inspector without debugging
- Adds support to run the VS Code debugger with MCP Inspector
- Adds support to attach a debugger in general to MCP Inspector

## What Changed
- Added `MCP_TRANSPORT` environment variable support to switch between
`stdio` (default for prod) and `streamable-http` (default for local dev
using `task` or VS Code debugger) transports
- Updated `task dev` and `task inspector` to work directly with the
Python interpreter by default for debugger compatibility (`mcp run`
defaults to `stdio` transport)
- Added `validate_transport` in `src/dbt_mcp/config/transport.py` to
properly handle transport types

Note: 
- `CONTRIBUTING.md` documents the three different options/workflows
enabled for local dev!
- This is a development-only change. Production usage remains unchanged
(the server defaults to `stdio` transport when `MCP_TRANSPORT` is not
set)

## Why
The `stdio` transport doesn't support Python debuggers because
stdin/stdout are all used up for MCP communication. With
`streamable-http` transport as an option, devs can now use full debugger
capabilities while testing with MCP Inspector.

## Related Issues
Closes #361

## Checklist
- [x] I have performed a self-review of my code
- [ ] I have made corresponding changes to the documentation (in
https://github.com/dbt-labs/docs.getdbt.com) if required
- [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

### Scenarios / Workflows Tested:

#### 1. Option 1: `task inspector` to simply use MCP Inspector (with
`stdio` transport) to run tools without debugging

MCP Inspector using STDIO transport:
<img width="1917" height="1263" alt="Screenshot 2025-10-07 at 3 40
08 PM"
src="https://github.com/user-attachments/assets/a2eea430-d35d-4171-951f-7b7e10ea1ab6"
/>

#### 2. Option 2: VS Code Debugger + MCP Inspector (`streamable-http`
transport)

MCP Inspector using Streamable HTTP transport:
<img width="1920" height="1280" alt="Screenshot 2025-10-07 at 3 37
32 PM"
src="https://github.com/user-attachments/assets/d90ad85b-b3a2-4e26-95a8-a3dfc9bfb7dd"
/>

VS Code debugger with breakpoint set (triggered by call in MCP Inspector
above ^^):
<img width="1683" height="1248" alt="Screenshot 2025-10-07 at 3 38
59 PM"
src="https://github.com/user-attachments/assets/b06d112e-d4ef-4c04-b195-1eb241759718"
/>

#### 3. Claude Desktop to ensure production server initialize still
works properly with `stdio` transport

Claude Desktop successfully uses my dev dbt MCP instance via STDIO
transport:
<img width="1224" height="861" alt="Screenshot 2025-10-07 at 8 53 03 AM"
src="https://github.com/user-attachments/assets/e8da6405-7f52-417a-9b2d-850da7ae69a4"
/>


Admittedly, I haven't yet tested "Option 3" from the `CONTRIBUTING.md`
file which involves manually attaching a debugger to the server that's
run with `task dev`. It's the same exact underlying principals as using
the VS Code debugger (which I have verified), but with more manual
configuration and use. I will try and put some time into that here soon.

Author: jairus-m

.changes/unreleased/Under the Hood-20251007-155717.yaml

@@ -0,0 +1,3 @@
+kind: Under the Hood
+body: Add support for Python debugger
+time: 2025-10-07T15:57:17.329501-07:00

.vscode/launch.json

@@ -1,6 +1,10 @@
 {
   "configurations": [
     {
+      "console": "integratedTerminal",
+      "env": {
+        "MCP_TRANSPORT": "streamable-http"
+      },
       "name": "debug dbt-mcp",
       "program": "${workspaceFolder}/src/dbt_mcp/main.py",
       "request": "launch",

CONTRIBUTING.md

@@ -76,7 +76,32 @@ Every PR requires a changelog entry. [Install changie](https://changie.dev/) and
 
 ## Debugging
 
-If you encounter any problems. You can try running `task run` to see errors in your terminal.
+The dbt-mcp server runs with `stdio` transport by default which does not allow for Python debugger support. For debugging with breakpoints, use `streamable-http` transport.
+
+### Option 1: MCP Inspector Only (No Breakpoints)
+1. Run `task inspector` - this starts both the server and inspector automatically
+2. Open MCP Inspector UI
+3. Use "STDIO" Transport Type to connect
+4. Test tools interactively in the inspector UI (uses `stdio` transport, no debugger support)
+
+### Option 2: VS Code Debugger with Breakpoints (Recommended for Debugging)
+1. Set breakpoints in your code
+2. Press `F5` or select "debug dbt-mcp" from the Run menu
+3. Open MCP Inspector UI via `npx @modelcontextprotocol/inspector`
+4. Connect to `http://localhost:8000/mcp/v1` using "Streamable HTTP" transport and "Via Proxy" connection type
+5. Call tools from Inspector - your breakpoints will trigger
+
+### Option 3: Manual Debugging with `task dev`
+1. Run `task dev` - this starts the server with `streamable-http` transport on `http://localhost:8000`
+2. Set breakpoints in your code
+3. Attach your debugger manually (see [debugpy documentation](https://github.com/microsoft/debugpy#debugpy) for examples)
+4. Open MCP Inspector via `npx @modelcontextprotocol/inspector`
+5. Connect to `http://localhost:8000/mcp/v1` using "Streamable HTTP" transport and "Via Proxy" connection type
+6. Call tools from Inspector - your breakpoints will trigger
+
+**Note:** `task dev` uses `streamable-http` by default. The `streamable-http` transport allows the debugger and MCP Inspector to work simultaneously without conflicts. To override, use `MCP_TRANSPORT=stdio task dev`.
+
+If you encounter any problems, you can try running `task run` to see errors in your terminal.
 
 ## Release
 

Taskfile.yml

@@ -59,16 +59,18 @@ tasks:
       - uv run src/dbt_mcp/main.py
 
   dev:
-    desc: "Run the dbt-mcp server in development mode"
+    desc: "Run the dbt-mcp server in development mode (with debugger support)"
+    env:
+      MCP_TRANSPORT: streamable-http
     cmds:
       - (cd ui && pnpm install && pnpm build)
-      - ./.venv/bin/mcp dev ./src/dbt_mcp/main.py
+      - ./.venv/bin/python ./src/dbt_mcp/main.py
 
   inspector:
     desc: "Run the dbt-mcp server with MCP inspector"
     cmds:
       - (cd ui && pnpm install && pnpm build)
-      - npx @modelcontextprotocol/inspector ./.venv/bin/mcp run src/dbt_mcp/main.py
+      - npx @modelcontextprotocol/inspector ./.venv/bin/python src/dbt_mcp/main.py
 
   test:
     desc: "Run the tests"

src/dbt_mcp/config/transport.py

@@ -0,0 +1,21 @@
+import logging
+from typing import Literal
+
+logger = logging.getLogger(__name__)
+
+TransportType = Literal["stdio", "sse", "streamable-http"]
+VALID_TRANSPORTS: set[TransportType] = {"stdio", "sse", "streamable-http"}
+
+
+def validate_transport(transport: str) -> TransportType:
+    """Validate and return the MCP transport type."""
+    transport = transport.strip().lower()
+
+    if transport not in VALID_TRANSPORTS:
+        valid_options = ", ".join(sorted(VALID_TRANSPORTS))
+        raise ValueError(
+            f"Invalid MCP_TRANSPORT: '{transport}'. Must be one of: {valid_options}"
+        )
+
+    logger.debug(f"Using MCP transport: {transport}")
+    return transport  # type: ignore[return-value]

src/dbt_mcp/main.py

@@ -1,12 +1,17 @@
 import asyncio
+import os
 
 from dbt_mcp.config.config import load_config
+from dbt_mcp.config.transport import validate_transport
 from dbt_mcp.mcp.server import create_dbt_mcp
 
 
 def main() -> None:
     config = load_config()
-    asyncio.run(create_dbt_mcp(config)).run()
+    server = asyncio.run(create_dbt_mcp(config))
+    transport = validate_transport(os.environ.get("MCP_TRANSPORT", "stdio"))
+    server.run(transport=transport)
 
 
-main()
+if __name__ == "__main__":
+    main()

tests/unit/config/test_transport.py

@@ -0,0 +1,21 @@
+import pytest
+
+from dbt_mcp.config.transport import validate_transport
+
+
+class TestValidateTransport:
+    def test_valid_transports(self):
+        assert validate_transport("stdio") == "stdio"
+        assert validate_transport("sse") == "sse"
+        assert validate_transport("streamable-http") == "streamable-http"
+
+    def test_case_insensitive_and_whitespace(self):
+        assert validate_transport("  STDIO  ") == "stdio"
+        assert validate_transport("SSE") == "sse"
+
+    def test_invalid_transport_raises_error(self):
+        with pytest.raises(ValueError) as exc_info:
+            validate_transport("invalid")
+
+        assert "Invalid MCP_TRANSPORT: 'invalid'" in str(exc_info.value)
+        assert "sse, stdio, streamable-http" in str(exc_info.value)