Paths: File paths (shared/, references/) are relative to skills repo root. Locate this SKILL.md directory and go up one level for repo root.

MCP Configurator

Type: L3 Worker Category: 0XX Shared

Configures MCP servers in Claude Code: audits state, registers servers, installs hooks and output style, migrates allowed-tools, updates instruction files, grants permissions, analyzes token budget.

Input / Output

Server Registry

Two transport types: stdio (local process) and HTTP (cloud endpoint).

hex-line/hex-ssh/hex-graph source selection: Prefer global install (npm i -g). Hooks require stable absolute path — npx cache is ephemeral and rejected by setup_hooks. Use local node {repo}/mcp/*/server.mjs only for active MCP development.

Workflow

Audit --> Update --> Configure --> Register --> Permissions --> Budget --> Report

Phase 1: Audit Current MCP State

1. Run claude mcp list — canonical source of truth for configured servers
   • Parse output: server name, transport type, connection status
   • Fallback if claude CLI unavailable: read ~/.claude.json + ~/.claude/settings.json, merge by server name
2. Build table of configured vs missing servers (compare against registry)
3. Check for deprecated servers and flag for removal:

Phase 2: Update Outdated npm Packages

For each hex MCP package (@levnikolaevich/hex-line-mcp, hex-ssh-mcp, hex-graph-mcp):

1. Check if globally installed: npm ls -g @levnikolaevich/hex-line-mcp --json 2>/dev/null
2. If installed, check for updates: npm outdated -g @levnikolaevich/hex-line-mcp
3. If outdated → run npm i -g @levnikolaevich/hex-line-mcp@latest
4. Report: "hex-line: 1.1.0 → 1.1.2 (updated)" or "hex-line: 1.1.2 (current)"

# Check and update all hex MCP packages:
for pkg in @levnikolaevich/hex-line-mcp @levnikolaevich/hex-ssh-mcp @levnikolaevich/hex-graph-mcp; do
  current=$(npm ls -g "$pkg" --json 2>/dev/null | node -e "try{console.log(JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).dependencies['${pkg}'].version)}catch{console.log('')}")
  if [ -n "$current" ]; then
    latest=$(npm view "$pkg" version 2>/dev/null)
    if [ "$current" != "$latest" ]; then
      npm i -g "${pkg}@latest"
      echo "$pkg: $current → $latest (updated)"
    else
      echo "$pkg: $current (current)"
    fi
  fi
done

Skip conditions:

• Package not installed globally → skip (Phase 3 handles fresh installs)
• dry_run: true → show planned update, do not execute
• Dev mode servers (local node {repo}/mcp/*/server.mjs) → skip npm update

Phase 3: Configure Missing Servers

For each server in registry not yet configured:

1. IF already configured AND claude mcp list shows connected → SKIP
2. IF dry_run: true → show planned claude mcp add command, do not execute
3. IF linear → ask user: "Do you use Linear for task management?" → no → SKIP

Phase 4: Register via claude mcp add

Registration commands by server and source:

Post-registration verification: After ALL servers are registered, run claude mcp list once. For each hex MCP (hex-line, hex-ssh, hex-graph): verify status is Connected. If any shows disconnected or missing — retry claude mcp add, then re-check. Report failures explicitly.

Error handling:

Phase 4b: Install Hooks and Output Style [CRITICAL]

MUST call mcp__hex-line__setup_hooks(agent="claude") immediately after hex-line registration. This configures:

Hooks (in ~/.claude/settings.json):

1. PreToolUse hook — redirects built-in Read/Edit/Write/Grep to hex-line equivalents
2. PostToolUse hook — compresses verbose tool output (RTK filter)
3. SessionStart hook — injects MCP Tool Preferences reminder
4. Sets disableAllHooks: false

Output Style: 5. Copies output-style.md to ~/.claude/output-styles/hex-line.md 6. Sets outputStyle: "hex-line" if no style is active (preserves existing style)

Verification: After setup_hooks returns, confirm the response contains Hooks configured for and does not contain SKIPPED, UNKNOWN_AGENT, Error, or failed. If error — STOP and report failure. Without hooks, hex-line pipeline does not work.

Phase 4c: Graph Indexing

After hex-graph registration + connected status:

1. mcp__hex-graph__index_project({ path: "{project_path}" }) — build initial code knowledge graph
2. mcp__hex-graph__watch_project({ path: "{project_path}" }) — enable live incremental updates on file changes

Skip if hex-graph not registered or not connected.

Phase 4d: Migrate Project allowed-tools [CRITICAL]

After hex-line is configured, MUST scan project commands and skills to replace built-in tools with hex-line equivalents in allowed-tools frontmatter. Failure to do this leaves commands using slow built-in tools despite hex-line being available.

Tool mapping:

Steps:

1. Glob .claude/commands/*.md + .claude/skills/*/SKILL.md in current project
2. For each file: parse YAML frontmatter, extract allowed-tools
3. For each mapping entry: a. If built-in present AND hex equivalent absent → add hex equivalent, remove built-in (except Read and Bash) b. If built-in present AND hex equivalent already present → remove built-in (except Read and Bash) c. Preserve ALL existing mcp__* tools not in the replacement table (e.g., mcp__hex-ssh__remote-ssh)
4. Write back updated frontmatter (preserve quoting style)
5. Report:

allowed-tools Migration:
| File                        | Tools Added                    | Status           |
|-----------------------------|--------------------------------|------------------|
| commands/deploy.md          | read_file, edit_file           | migrated         |
| commands/run-tests.md       | —                              | already migrated |
| commands/review.md          | —                              | no allowed-tools |

Skip conditions:

Strategy: REPLACE built-in tools with hex-line equivalents. Keep Bash and Read (always needed). Preserve all existing mcp__* tools (hex-ssh, linear, etc.) that are NOT being replaced.

Phase 4e: Update Instruction Files [CRITICAL]

After hex-line is configured with hooks, ensure instruction files have MCP Tool Preferences section. Without this section, agents default to built-in tools in every session — negating the entire hex-line setup.

MANDATORY READ: Load mcp/hex-line-mcp/output-style.md → use its # MCP Tool Preferences section as template. MUST include the full table (Read, Edit for hash edits, Write, Grep, bulk_replace for text rename).

Steps (MUST execute all):

1. For each file: CLAUDE.md, GEMINI.md, AGENTS.md (if exists in project):
2. Search for ## MCP Tool Preferences or ### MCP Tool Preferences
3. If MISSING → MUST insert section before ## Navigation (or at end of conventions/rules block)
4. If PRESENT but OUTDATED → MUST update table rows to match template
5. For GEMINI.md: MUST adapt tool names (Read → read_file, Edit → edit_file, Grep → search_files)

Skip conditions:

Phase 5: Grant Permissions

For each configured MCP server, add mcp__{name} to ~/.claude/settings.json → permissions.allow[].

1. Read ~/.claude/settings.json (create if missing: {"permissions":{"allow":[]}})
2. For each configured server: check if mcp__{name} already in allow[]
3. Missing → append
4. Write back (2-space indent JSON)
5. Report: "Granted N permissions (M already present)"

Idempotent: existing entries skipped.

Phase 6: Budget Analysis

Budget warnings:

Phase 7: Report

MCP Configuration:
| Server    | Transport | Status        | Permission | Detail                  |
|-----------|-----------|---------------|------------|-------------------------|
| hex-line  | stdio     | configured    | granted    | global npm (hex-line-mcp) |
| hex-ssh   | stdio     | added         | granted    | global npm (hex-ssh-mcp)  |
| context7  | HTTP      | configured    | granted    | mcp.context7.com        |
| Ref       | HTTP      | configured    | granted    | api.ref.tools (key set) |
| linear    | HTTP      | skipped       | skipped    | user declined           |

Budget: 4 servers ~ 20K tokens (10.0% of context) — OK

Phase 8: Token Efficiency Benchmark

After hex-line is configured, run benchmark on user's repo:

node "$(npm root -g)/@levnikolaevich/hex-line-mcp/benchmark/index.mjs"

Display results to user — demonstrates value of the MCP setup just completed.

Key metrics shown:

• Outline vs full read savings (expect 57-93% on medium-XL files)
• Compact diff savings (expect 32-38% on edits)
• Hash overhead (expect ~0% — negligible)
• Break-even point (typically ~30 lines)

Report savings summary to user.

Critical Rules

1. Write only via sanctioned paths. Register servers via claude mcp add. Write to ~/.claude/settings.json ONLY for hooks (via setup_hooks), permissions (permissions.allow[]), and outputStyle
2. Verify after add. Always run claude mcp list after registration to confirm connection
3. Ask before optional servers. Linear requires explicit user consent
4. Prefer global install. Use npm i -g for hex-line/hex-ssh/hex-graph — hooks need stable paths. Local only for active MCP development
5. Remove deprecated servers. Clean up servers no longer in the registry
6. Grant permissions. After registration, add mcp__{server} to user ~/.claude/settings.json

Anti-Patterns

Definition of Done

• Current MCP state audited via claude mcp list
• Outdated hex-* npm packages updated (or skipped if current)
• Missing required servers registered via claude mcp add
• Each registered server verified via claude mcp list
• Hooks installed in settings.json (PreToolUse, PostToolUse, SessionStart) and disableAllHooks: false
• Output style installed (outputStyle: "hex-line" or existing style preserved)
• Token budget calculated and warnings shown if applicable
• Final status table displayed with all servers
• Permissions granted for all configured servers in user settings
• Project allowed-tools migrated: built-ins replaced with hex-line, existing mcp__* preserved
• MCP Tool Preferences section present in all existing instruction files
• Token efficiency benchmark run and results shown

Version: 1.1.0 Last Updated: 2026-03-20