MCP Servers hook error when installed via Agent Package Manage(APM)

[sny-13]

Summary

When databricks-solutions/ai-dev-kit is installed via APM (Agent Package Manager) instead of Claude Code's
native plugin marketplace, the SessionStart hook (setup.sh) fails on first run and the databricks MCP server never starts. The skills are visible
(APM deploys them under .claude/skills/), but every mcp__databricks__* tool is unreachable.

The root cause is a layout assumption in setup.sh that holds for Claude Code's native plugin install but not for APM's split deployment.

Environment

• OS: macOS 15 (Darwin 25.5.0) — also reproducible on Linux
• Shell: zsh / bash 3.2
• Python: 3.11 via uv
• Plugin commit: 76c774faec57fbb1b78fc8482ba64bf762bb42b1 (current main)
• APM version: 0.16.1
• Claude Code: current

Background: how APM's layout differs from Claude Code's plugin layout

Claude Code's native plugin install keeps the whole plugin tree together and exports CLAUDE_PLUGIN_ROOT when invoking hooks. APM splits the plugin
across two locations:

Asset	Native plugin install	APM install
Hook scripts	<plugin-root>/.claude-plugin/setup.sh	<repo>/.claude/hooks/ai-dev-kit/.claude-plugin/setup.sh
Python payload (databricks-tools-core, databricks-mcp-server)	<plugin-root>/databricks-*
<repo>/apm_modules/databricks-solutions/ai-dev-kit/databricks-*
CLAUDE_PLUGIN_ROOT env var at hook runtime	set by Claude Code	not set

The two locations are no longer siblings, and the env var that would otherwise paper over the difference is absent.

Bug 1: setup.sh PLUGIN_ROOT fallback assumes hook lives next to the python payload

In .claude-plugin/setup.sh:

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
TOOLS_CORE_DIR="${PLUGIN_ROOT}/databricks-tools-core"
MCP_SERVER_DIR="${PLUGIN_ROOT}/databricks-mcp-server"

Under APM, CLAUDE_PLUGIN_ROOT is unset, so the fallback resolves to <repo>/.claude/hooks/ai-dev-kit/. That directory does not contain
databricks-tools-core/ or databricks-mcp-server/ — they live under apm_modules/databricks-solutions/ai-dev-kit/. The script aborts:

$ bash .claude/hooks/ai-dev-kit/.claude-plugin/setup.sh
Setting up Databricks AI Dev Kit...
Error: databricks-tools-core not found at /<repo>/.claude/hooks/ai-dev-kit/databricks-tools-core

.venv is never created, and on the next session start the databricks MCP server fails to launch.



Bug 2: .mcp.json ships an unresolved ${CLAUDE_PLUGIN_ROOT} placeholder

.mcp.json:

{
  "mcpServers": {
    "databricks": {
      "command": "${CLAUDE_PLUGIN_ROOT}/.venv/bin/python",
      "args": ["${CLAUDE_PLUGIN_ROOT}/databricks-mcp-server/run_server.py"],
      "defer_loading": true
    }
  }
}

Claude Code expands ${CLAUDE_PLUGIN_ROOT} only when launching MCP servers that belong to a registered plugin. APM emits this file as a project-level
.mcp.json (no plugin context), so the variable is never substituted and the databricks server can't be started — even after a successful setup.sh.

This is partly an APM-side concern (its install step could rewrite the placeholder, and in fact APM's own apm.lock.yaml already records correctly
resolved absolute paths for the databricks server). But the plugin can mitigate this in the same way #510 suggests for Windows: ship a small launcher
 script and reference it from .mcp.json:

{
  "mcpServers": {
    "databricks": {
      "command": "bash",
      "args": ["${CLAUDE_PLUGIN_ROOT}/.claude-plugin/launch_server.sh"],
      "defer_loading": true
    }
  }
}

…where launch_server.sh reuses the same resolve_plugin_root logic above. This collapses Bug 2 into Bug 1: anywhere the launcher can find its payload,
 the MCP server starts.

Reproduction

1. In a project that uses APM, add the plugin to apm.yml:
dependencies:
  apm:
    - databricks-solutions/ai-dev-kit
2. Run apm install (apm 0.16.1).
3. Confirm the split layout — payload at apm_modules/databricks-solutions/ai-dev-kit/, hook copy at .claude/hooks/ai-dev-kit/.claude-plugin/setup.sh.
4. Run the deployed hook directly:
bash .claude/hooks/ai-dev-kit/.claude-plugin/setup.sh
4. → fails with Error: databricks-tools-core not found at .../.claude/hooks/ai-dev-kit/databricks-tools-core.
5. Start a Claude Code session. The databricks MCP server is listed but never starts; mcp__databricks__* tools are unreachable.


## Impact

Affects every team consuming the plugin via APM

[sny-13]

Workaround

Until the plugin is APM-aware, users on APM can:

1. Manually create the venv against the apm_modules payload:
   cd apm_modules/databricks-solutions/ai-dev-kit
   uv venv --python 3.11
   uv pip install --python .venv/bin/python -e ./databricks-tools-core
   uv pip install --python .venv/bin/python -e ./databricks-mcp-server
2. Replace the project-level .mcp.json databricks entry with absolute paths (these are already in apm.lock.yaml):
   "databricks": {
   "type": "stdio",
   "command": "/abs/path/to/apm_modules/databricks-solutions/ai-dev-kit/.venv/bin/python",
   "args": ["/abs/path/to/apm_modules/databricks-solutions/ai-dev-kit/databricks-mcp-server/run_server.py"]
   }