fix(databricks): correct MCP onboarding, harden credential detection, fix support routing

[antonyprasad-db]

Summary

Three groups of corrections to the Databricks Power's documentation, all cases of text that was accurate when written and went stale when something around it changed. No skill or tool content changes.

1. The MCP onboarding cannot work as documented

install.sh in ai-dev-kit became skills-only on 2026-07-28 (PR #562, "Install skills from databricks-agent-skills via databricks aitools") and now delegates skill installation to the Databricks CLI. Its own header reads "The (deprecated, optional) MCP server has its own installer." This Power was published 2026-05-19 against the earlier behaviour and was never updated.

Verified on macOS with Kiro 1.0.182. Four things have to line up, and the documented flow gets none of them:

1. install.sh no longer builds ~/.ai-dev-kit/.venv. Only databricks-mcp-server/mcp_install.sh does, and the Power never invokes it.
2. mcp_install.sh cannot be piped from curl. It resolves its own location from BASH_SOURCE[0], so under bash <(curl …):

   Venv:  /dev/.venv
   ✗ MCP setup script not found at /dev/fd/setup.sh
   

   Reproduced twice. It must run from a checkout.
3. Its default venv location is <clone>/.venv, not the path mcp.json references. --venv-dir "$HOME/.ai-dev-kit/.venv" is required.
4. Step 1's own verification checks for that venv, so it fails on every fresh install — and the troubleshooting entry blames a missing prerequisite. uv and git were installed and working throughout.

The server itself is fine. Running the correct installer with --venv-dir gave [databricks] mcp.connect.ok and a live tool call returning real data. This is only an instructions problem, so the PR adds the missing step rather than removing the capability.

Changes: add Step 1b with both constraints and a note that MCP connects at IDE launch rather than chat-session start; rewrite the "venv is missing" troubleshooting entry; correct Step 1's verification; mark --skills-only as no longer meaningful for MCP; promote the Databricks CLI from optional to required v1.0.0+; correct Step 2.6, which attributed the standalone mcpServers.databricks entry to install.sh; reframe the description and overview so the 44 MCP tools read as an optional add-on.

Also adds a pre-flight rule to the Agent First-Action Protocol: never report the MCP server as working without confirming the interpreter exists. The protocol checked credentials but not whether the server could spawn, so an agent reading a populated mcp.json reported it as "already wired into your top-level MCP config and working" while the log showed:

[error] [databricks] Failed to connect: spawn …/.ai-dev-kit/.venv/bin/python ENOENT

It then offered to pick a profile and enable it, which cannot help — the failure is at spawn, before any profile is read.

2. Credential detection could echo the secrets it is told not to echo

The onboarding rules already say to show identifiers and fingerprints and never the full secret, with a Display/Hide table covering PATs, client secrets and cached tokens. Those rules are right. But they are addressed to an agent with shell access, and on a real run the agent satisfied step 1 by doing this:

cat ~/.databrickscfg 2>/dev/null || echo "NO_DATABRICKSCFG"

That prints every token and client_secret in the file into the chat transcript before step 2 is ever consulted. Nothing was exposed in my case because the profile used OAuth, but Option D of this same document tells users to store a PAT in exactly that file.

"Never echo the secret" is not enforceable as a request. Step 1 now prescribes field-selecting commands instead, so the secret is never selected and therefore cannot be echoed:

awk '/^\[/{p=$0} /^[[:space:]]*(host|auth_type|client_id)[[:space:]]*=/{print p, $0}' \
  ~/.databrickscfg 2>/dev/null || echo "NO_DATABRICKSCFG"

Plus a python3 one-liner for mcp.json that omits env values, since those can hold a PAT. And a note that fingerprints for rule 2 must be extracted per-field rather than by printing the file and trimming afterwards.

3. Support routing pointed at a personal repository

"Power packaging / installation issues" directed users to github.com/venkatavaradhanv/databricks/issues — a personal repository with no activity since 2026-05-20. Issues filed there are unlikely to be seen. Now points at this catalog's tracker. The same repository remains credited under Contributors, which is the right place for it.

4. Authorship and product names

The Trademarks section stated the Power is "not authored, endorsed, or maintained by Databricks, Inc." and described it as community-published, while the frontmatter declares author: "Databricks" and Kiro presents it that way.

That was accurate originally — it began as a third-party wrapper around a public installer — but stopped being true once it was published to this catalog under Databricks' name.

It is also the only disclaimer of its kind in the catalog. Every other vendor-named power simply names itself as author, with no disclaimer and no trademark section:

Neon, Stripe, Datadog, Dynatrace, HashiCorp, StackGen, Checkout.com  → author: <vendor>, no disclaimer
databricks                                                          → author: "Databricks" + disclaimer

Removed the contradiction, kept the trademark attribution, and brought the entry in line with the rest of the catalog.

Product names: removed a stale product reference, and named Unity AI Gateway correctly where it was previously written as bare "AI Gateway". The trademark list now covers the products actually referenced.

One question for your team

Both deliberately left open rather than decided:

Should the Power own the MCP entry, or the standalone entry the installer writes? Both exist today, the Power's ships disabled: true, and the standalone one is what actually runs. That changes which component owns the server, so it seemed like your call rather than mine.

One question I answered rather than asking

I had intended to ask whether command supports ${HOME}, which would let mcp.json ship a working path and delete Step 2.7 entirely. It does not, and the reason is worth recording:

Kiro does expand ${VAR} in MCP config, including under powers.mcpServers — but the expansion is gated on the kiroAgent.mcpApprovedEnvVars setting. Any variable not on that list is returned as a literal string and only recorded for an unapproved-variable warning:

let a = expandAll ? undefined : getConfiguration("kiroAgent").get(mcpApprovedEnvVars, []);
return t.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (match, name) => {
    if (a && !a.includes(name)) return unapproved.add(name), match;   // left literal

That setting is per-user, so a catalog-published Power cannot add HOME to it, and ${HOME} would ship broken for anyone who had not approved it by hand. It also explains why the env block's ${DATABRICKS_CONFIG_PROFILE} resolves correctly — that variable does end up on the approved list.

So mcp.json is unchanged and Step 2.7 stays, but it now documents why rather than reading like an oversight. Correct me if I have misread the gating.

Testing

All internal anchors resolve, code fences balanced, frontmatter intact. Every behavioural claim was reproduced on a real install rather than inferred — the curl-pipe failure, the venv path mismatch, the successful connection after correcting both, and the agent misreporting its own state.

[antonyprasad-db]

@nadetastic — when you get a moment, this one's ready for a look. Same Power you reviewed and merged in #129.

Short version: the MCP setup steps in POWER.md can't be followed as written any more. Our installer moved to skills-only and the MCP server split out into its own script, so the documented flow doesn't produce the venv that mcp.json then points at. The skills half is unaffected — that part works.

Beyond the setup flow it also hardens the credential-detection step so it can't echo a secret to the terminal, and fixes the support link, which pointed at the wrong repo.

No rush at all. Happy to split it if you'd rather take the setup correction on its own and leave the rest for later.