Route all MCP clients through a uniform ucode mcp-proxy stdio bridge (#201)

* Route all MCP clients through a uniform `ucode mcp-proxy` stdio bridge

Every coding agent now registers Databricks MCP servers as one identical local
stdio command — `ucode mcp-proxy --url <endpoint> --host <ws> --profile <p>` —
instead of per-client HTTP-bearer entries. This replaces five divergent auth
paths (claude `${OAUTH_TOKEN}` header, codex `--bearer-token-env-var`, gemini
`--header`, opencode `{env:OAUTH_TOKEN}`, copilot `Bearer ${OAUTH_TOKEN}`), none
of which refreshed the token mid-session, with a single mechanism.

Why a proxy: MCP clients disagree on HTTP-auth config and none expose a
per-request auth hook (except Claude's headersHelper), so a static bearer froze
at launch and expired after ~1h. A local stdio proxy sidesteps all of that: the
client spawns it as a child process (and reaps it — ucode owns no long-lived
process or refresh thread), and the proxy mints a fresh OAuth token from the
Databricks CLI profile on every upstream request. The proxy is an invisible
implementation detail baked into each client's config; users never invoke it.

- src/ucode/mcp_proxy.py (new): stdio<->streamable-HTTP bridge built on the
  official `mcp` SDK. `httpx.Auth` injects a fresh `get_databricks_token(...)`
  bearer per request; a transport-level pump forwards messages both ways, so new
  MCP methods/capabilities pass through untouched.
- cli.py: hidden `ucode mcp-proxy --url --host --profile --use-pat` command.
- databricks.py: `build_mcp_proxy_argv(...)` (mirrors build_auth_token_argv).
- mcp.py: add_{claude,codex,gemini}_mcp_server + opencode/copilot writers now
  register the stdio proxy argv; removed build_mcp_http_entry / OAUTH_TOKEN
  header. add_claude_mcp_server stays polymorphic so the web_search stdio entry
  (a dict with its own env) still registers via add-json.
- pyproject: add `mcp>=1.28.0`.

Verified against a live workspace: `ucode mcp-proxy` handshakes stdio and returns
the endpoint's tools (initialize OK, tools/list OK); ucode's real codex
registration lists the proxy as an enabled stdio server. Tests: 864 pass
(2 pre-existing e2e network failures unrelated); ruff + ty clean.

Co-authored-by: Isaac

* ci: resolve deps against public PyPI on hosted runners

uv.lock pins packages to Databricks' internal pypi-proxy, which GitHub
hosted runners can't reach — dependency downloads time out (~44s x3 retries)
before any test runs, failing both the test and e2e jobs.

Set UV_INDEX_URL=https://pypi.org/simple on both jobs and add a `uv lock`
step before install so the lockfile is re-resolved against public PyPI at
CI time. Per Aarushi Shah's suggestion.

Co-authored-by: Isaac

Author: sunishsheth2009

.github/workflows/ci.yml

@@ -12,14 +12,23 @@ permissions:
 jobs:
   test:
     runs-on: ubuntu-latest
+    env:
+      # uv.lock pins packages to Databricks' internal pypi-proxy, which hosted
+      # GitHub runners can't reach (downloads time out). Re-resolve against
+      # public PyPI at CI time: UV_INDEX_URL + a `uv lock` before install.
+      UV_INDEX_URL: https://pypi.org/simple
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
       - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b  # v8.1.0
+      - run: uv lock
       - run: uv run pytest --ignore=tests/test_e2e.py --ignore=tests/test_e2e_tracing.py
 
   e2e:
     runs-on: ubuntu-latest
     env:
+      # See the test job: hosted runners can't reach the internal pypi-proxy,
+      # so resolve against public PyPI (paired with the `uv lock` step below).
+      UV_INDEX_URL: https://pypi.org/simple
       UCODE_TEST_WORKSPACE: ${{ secrets.UCODE_TEST_WORKSPACE }}
       DATABRICKS_HOST: ${{ secrets.UCODE_TEST_WORKSPACE }}
       # DATABRICKS_BEARER is the CI escape hatch: `databricks auth token`
@@ -47,6 +56,7 @@ jobs:
           opencode-ai
           @github/copilot
           @earendil-works/pi-coding-agent
+      - run: uv lock
       - run: uv tool install .
       # Redirect stdin so any interactive `databricks auth login --no-browser`
       # fallback EOFs instead of hanging the runner. With DATABRICKS_BEARER

README.md

@@ -89,8 +89,13 @@ Options are shown in this order:
 - Managed Databricks MCPs (Vector Search, UC Functions, etc.)
 - Custom MCP server URL
 
-Discovered external MCP connections are listed directly. MCP auth uses a Databricks token that
-`ucode` sets when launching each tool.
+Discovered external MCP connections are listed directly.
+
+Every Databricks MCP server is registered as a local **stdio** server that runs `ucode mcp-proxy`
+— a small bridge (shipped with `ucode`) between the coding tool and the Databricks
+streamable-HTTP MCP endpoint. The proxy mints a fresh OAuth token from your Databricks CLI profile
+on every request, so MCP auth is handled uniformly for every client and never expires mid-session.
+The coding tool starts and stops the proxy as a child process; there's nothing extra to run.
 
 To set up an agent and its MCP server(s) in one command, pass `--mcp` with fully-qualified
 service name(s) to `ucode configure`:

pyproject.toml

@@ -10,6 +10,10 @@ readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [
   "databricks-sql-connector>=3.6.0",
+  # `ucode mcp-proxy` bridges a client's stdio MCP transport to a Databricks
+  # streamable-HTTP MCP endpoint, injecting a freshly-minted OAuth bearer per
+  # request. Uses the official MCP SDK's stdio server + streamable-HTTP client.
+  "mcp>=1.28.0",
   "questionary>=2.0.0",
   "tomlkit>=0.13.0",
   "typer>=0.12.0",

src/ucode/agents/copilot.py

@@ -99,25 +99,27 @@ def build_runtime_env(workspace: str, model: str, token: str) -> dict[str, str]:
     return env
 
 
-def build_mcp_server_entry(url: str) -> dict:
+def build_mcp_server_entry(argv: list[str]) -> dict:
+    # A `local` MCP server runs a stdio command; `command`/`args` split the
+    # argv. ucode registers the `ucode mcp-proxy ...` bridge here so Copilot
+    # never speaks HTTP+bearer directly — the proxy handles token refresh. The
+    # OAUTH_TOKEN env Copilot still injects at launch is for MODEL auth, not MCP.
     return {
-        "type": "http",
-        "url": url,
-        "headers": {
-            "Authorization": "Bearer ${OAUTH_TOKEN}",
-        },
+        "type": "local",
+        "command": argv[0],
+        "args": list(argv[1:]),
         "tools": ["*"],
     }
 
 
-def write_mcp_server_config(name: str, url: str) -> bool:
+def write_mcp_server_config(name: str, argv: list[str]) -> bool:
     backup_existing_file(COPILOT_MCP_CONFIG_PATH, COPILOT_MCP_BACKUP_PATH)
     existing = read_json_safe(COPILOT_MCP_CONFIG_PATH)
     mcp_servers = existing.get("mcpServers")
     if not isinstance(mcp_servers, dict):
         mcp_servers = {}
     removed = name in mcp_servers
-    mcp_servers[name] = build_mcp_server_entry(url)
+    mcp_servers[name] = build_mcp_server_entry(argv)
     existing["mcpServers"] = mcp_servers
     write_json_file(COPILOT_MCP_CONFIG_PATH, existing)
     return removed

src/ucode/agents/opencode.py

@@ -29,7 +29,6 @@
 OPENCODE_CONFIG_DIR = OPENCODE_XDG_CONFIG_HOME / "opencode"
 OPENCODE_CONFIG_PATH = OPENCODE_CONFIG_DIR / "opencode.json"
 OPENCODE_BACKUP_PATH = APP_DIR / "opencode-config.backup.json"
-OPENCODE_MCP_AUTH_HEADER_VALUE = "Bearer {env:OAUTH_TOKEN}"
 
 SPEC: ToolSpec = {
     "binary": "opencode",
@@ -193,25 +192,25 @@ def write_tool_config(
     return state, token
 
 
-def build_mcp_server_entry(url: str) -> dict:
+def build_mcp_server_entry(argv: list[str]) -> dict:
+    # A `local` MCP server runs a command over stdio; `command` is the full
+    # argv. ucode registers the `ucode mcp-proxy ...` bridge here so OpenCode
+    # never speaks HTTP+bearer directly — the proxy mints fresh tokens itself.
     return {
-        "type": "remote",
-        "url": url,
+        "type": "local",
+        "command": list(argv),
         "enabled": True,
-        "headers": {
-            "Authorization": OPENCODE_MCP_AUTH_HEADER_VALUE,
-        },
     }
 
 
-def write_mcp_server_config(name: str, url: str) -> bool:
+def write_mcp_server_config(name: str, argv: list[str]) -> bool:
     backup_existing_file(OPENCODE_CONFIG_PATH, OPENCODE_BACKUP_PATH)
     existing = read_json_safe(OPENCODE_CONFIG_PATH)
     mcp_servers = existing.get("mcp")
     if not isinstance(mcp_servers, dict):
         mcp_servers = {}
     removed = name in mcp_servers
-    mcp_servers[name] = build_mcp_server_entry(url)
+    mcp_servers[name] = build_mcp_server_entry(argv)
     existing["mcp"] = mcp_servers
     write_json_file(OPENCODE_CONFIG_PATH, existing)
     return removed

src/ucode/cli.py

@@ -868,6 +868,43 @@ def mcp_web_search_cmd() -> None:
     serve()
 
 
+@app.command("mcp-proxy", hidden=True)
+def mcp_proxy_cmd(
+    url: Annotated[
+        str,
+        typer.Option("--url", help="Databricks streamable-HTTP MCP endpoint to forward to."),
+    ],
+    host: Annotated[
+        str | None,
+        typer.Option(
+            "--host", help="Workspace URL for token minting. Defaults to the saved workspace."
+        ),
+    ] = None,
+    profile: Annotated[
+        str | None, typer.Option("--profile", help="Databricks CLI profile.")
+    ] = None,
+    use_pat: Annotated[
+        bool, typer.Option("--use-pat", help="Use the profile's static PAT instead of OAuth.")
+    ] = False,
+) -> None:
+    """Bridge a coding agent's stdio MCP transport to a Databricks MCP endpoint.
+
+    Each configured client spawns this as a local stdio MCP server (see
+    `ucode configure mcp`); it forwards messages to ``--url`` and injects a
+    freshly-minted OAuth bearer on every upstream request, so the token never
+    expires mid-session. Not meant for interactive use — the agent manages this
+    process's lifecycle."""
+    from ucode.mcp_proxy import serve
+
+    state = load_state()
+    workspace = host or state.get("workspace")
+    if not workspace:
+        print_err("No workspace configured. Run `ucode configure` first.")
+        raise typer.Exit(1)
+    profile = profile or state.get("profile")
+    serve(url, workspace, profile, use_pat=use_pat or bool(state.get("use_pat")))
+
+
 @app.command("auth-token", hidden=True)
 def auth_token_cmd(
     host: Annotated[

src/ucode/databricks.py

@@ -1138,6 +1138,27 @@ def build_auth_token_argv(
     return argv
 
 
+def build_mcp_proxy_argv(
+    url: str, workspace: str, profile: str | None = None, *, use_pat: bool = False
+) -> list[str]:
+    """Argv for the stdio MCP bridge: `ucode mcp-proxy --url ... --host ...`.
+
+    Every coding agent registers this single command as a local stdio MCP
+    server instead of a per-client HTTP endpoint with a bearer header. The proxy
+    forwards to ``url`` and mints a fresh OAuth token on each upstream request,
+    so tokens never expire mid-session — the client only ever spawns a process,
+    which keeps registration uniform across CLIs that disagree on HTTP-auth
+    syntax. Like `build_auth_token_argv`, this resolves the absolute `ucode`
+    path and passes plain arguments (no shell), so it runs identically on every
+    platform."""
+    argv = [_ucode_binary(), "mcp-proxy", "--url", url, "--host", workspace.rstrip("/")]
+    if profile:
+        argv += ["--profile", profile]
+    if use_pat:
+        argv.append("--use-pat")
+    return argv
+
+
 def build_auth_shell_command(
     workspace: str, profile: str | None = None, *, use_pat: bool = False
 ) -> str: