Add ucode configure skills --location to register the UC Skills MCP

[xsh310]

What & why

Adds a non-interactive command that registers the Unity Catalog Skills MCP endpoint for a <catalog>.<schema>, replacing the manual ~/.claude.json edit used during the skills bug bash:

ucode configure skills --location <catalog>.<schema>

The endpoint (/ai-gateway/skills/<cat>/<sch>) is added to every configured MCP-capable agent (Claude, Codex, Gemini, OpenCode, Copilot). Claude Code additionally receives alwaysLoad: true so the schema's skills are eagerly loaded and discoverable; the other agents get the same endpoint from the URL alone, which their CLIs cannot express.

Implementation

• databricks.py — build_skills_mcp_url() builds {ws}/ai-gateway/skills/{cat}/{sch} (path segments, unlike the dotted mcp-services route).
• mcp.py
  • build_mcp_http_entry(url, *, always_load=False) adds alwaysLoad when requested.
  • Skills entries are tagged kind: "skills" in saved state; apply_mcp_server_changes derives always_load from that tag. The field rides in the shared entry dict but only Claude's mcp add-json path consumes it — other agents are registered from the URL alone.
  • _resolve_skills_mcp_servers registers exactly one skills entry, preserving coexisting mcp-services and dropping any stale skills entry so re-runs repoint cleanly.
  • configure_skills_command() fans out to all configured agents via the existing apply path.
• cli.py — configure skills subcommand with a required --location; ucode status labels skills entries (skills).
• Refactor (no behavior change): the non-interactive preamble shared by the mcp and skills commands is extracted into _setup_mcp_clients, and the <catalog>.<schema> validation into _split_catalog_schema.

Out of scope

• Skills-schema discovery / interactive picker (one --location per invocation for now).
• Eager loading for non-Claude agents (their CLIs can't express it).

Testing

Unit tests

• 882 unit tests pass (uv run pytest, excluding e2e); ruff check, ruff format --check, and ty all clean.
• New coverage: URL builder, alwaysLoad on/off, per-agent dispatch (Claude gets the entry, Codex gets URL-only), skills registration across all agents, stale-skills replacement while preserving mcp-services, malformed --location, and CLI wiring (dispatch, required flag, error exit code).

Manual end-to-end (against a real workspace)

Ran against staging workspace eng-ml-inference.staging.cloud.databricks.com with a real skills schema xsh.xsh_oncall_skills, configuring both Claude Code and Codex:

ucode configure --profiles eng-ml-inference-staging --agents claude,codex
ucode configure skills --location xsh.xsh_oncall_skills

Config written correctly:

Check	Result
Registered for every configured agent	✅ Claude + Codex
Claude entry (~/.claude.json) has alwaysLoad: true	✅
Codex entry (~/.codex/config.toml) is URL-only, no alwaysLoad	✅ (bearer_token_env_var = "OAUTH_TOKEN", no alwaysLoad key)
URL preserves the real schema; server name is agent-safe	✅ URL …/skills/xsh/xsh_oncall_skills; name databricks-skills-xsh-xsh-oncall-skills (dots/underscores slugified since agent CLIs reject them)
ucode status labels the entry (skills)	✅ under both agents
Coexists with other MCP servers; re-running repoints cleanly	✅

Auth + live connection verified. The entry authenticates with Bearer ${OAUTH_TOKEN}, which ucode injects into the agent's environment at launch (claude.py), so a directly-launched agent returns 401 while an agent launched via ucode claude gets a fresh token. Confirmed both cases against the endpoint's MCP initialize:

• empty token (direct launch) → HTTP 401 (expected)
• real ucode-injected token → HTTP 200

Skills actually load. Launched Claude via ucode claude; /mcp shows the server connected, and tools/list returns 11 tools — the 5 skills from xsh.xsh_oncall_skills exposed as skill_<leaf> plus the 6 static utility tools (load_skill, get_skill_files, list_skills, create_skill, update_skill, delete_skill). tools/call verified working on the loaded skills.

Note on auth UX

Like all ucode-managed Databricks MCP servers, the skills entry relies on OAUTH_TOKEN being present in the agent's environment, which only happens when the agent is launched through ucode (ucode claude, ucode codex, …). Opening the agent directly yields a 401. This matches existing ucode MCP behavior and is more secure than baking a static PAT into the config (as the manual bug-bash setup did), but it's a sharp edge worth documenting for users.