MCP Absolute Path Config

MCP Absolute Path Configuration

Experiment Overview

Context

Claude Code failed to start the KINTSUGI MCP server because the config used a bare command name ("command": "kintsugi") which isn't on PATH when the conda env isn't activated (typical for HPC login nodes, VS Code terminals, etc.).

Additionally, the old code incorrectly put mcpServers in .claude/settings.local.json — that field is not recognized there. MCP server definitions belong in .mcp.json at the project root.

Verified Workflow

1. Helper function resolves absolute path

# src/kintsugi/project.py
def _resolve_kintsugi_executable() -> str:
    """Resolve absolute path to the kintsugi CLI executable."""
    import shutil
    import sys
    from pathlib import Path

    path = shutil.which("kintsugi")
    if path:
        return str(Path(path).resolve())

    candidate = Path(sys.executable).parent / "kintsugi"
    if candidate.exists():
        return str(candidate.resolve())

    return "kintsugi"

2. MCP config goes in .mcp.json (NOT settings.local.json)

// .mcp.json (project root)
{
  "mcpServers": {
    "kintsugi": {
      "command": "/blue/maigan/smith6jt/miniforge3/envs/KINTSUGI/bin/kintsugi",
      "args": ["mcp", "start"],
      "cwd": "/blue/maigan/smith6jt/KINTSUGI"
    }
  }
}

3. Settings file enables the server

// .claude/settings.local.json
{
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": ["kintsugi"]
}

4. CLI commands create both files

kintsugi mcp config /path/to/project   # Creates .mcp.json + settings.local.json
kintsugi init /path/to/project          # Also creates both files

Failed Attempts (Critical)

Final Parameters

# Resolution order for executable path:
# 1. shutil.which("kintsugi") — works if env is activated
# 2. Path(sys.executable).parent / "kintsugi" — same conda env, no PATH needed
# 3. "kintsugi" — bare name fallback (may fail)

Key Insights

• .claude/settings.local.json does NOT support mcpServers — it only supports enabledMcpjsonServers (list of server names from .mcp.json)
• sys.executable sibling trick works because pip-installed entry points live next to the Python interpreter in the same conda env's bin/ directory
• The .mcp.json file is checked into version control for team sharing; settings.local.json is typically local
• Claude Code prompts for approval before using project-scoped MCP servers from .mcp.json

References

• Claude Code MCP docs: https://code.claude.com/docs/en/mcp
• Claude Code settings schema: mcpServers only valid in .mcp.json, ~/.claude.json, or managed-mcp.json