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: installs npm packages, registers servers, installs hooks and output style, migrates allowed-tools, updates instruction files, grants permissions.

Input / Output

Server Registry

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

Workflow

Install → Register & Configure → Hooks → Permissions → Migrate → Report

Phase 1: Install & Verify MCP Packages

Smart install: check MCP status first, then npm versions. Skip what's already working.

Step 1a: Check MCP server status

Run claude mcp list → parse each hex server:

Step 1b: Check for npm updates (connected servers only)

Run npm outdated -g @levnikolaevich/{pkg} for each connected server's package:

Step 1c: Install missing / broken packages

For servers not found or disconnected in Step 1a:

1. npm i -g @levnikolaevich/{pkg}
2. Verify: npm ls -g @levnikolaevich/{pkg} --json

Decision flow per server:

claude mcp list → connected? ─── yes ──→ npm outdated → outdated? ── yes ──→ npm i -g (update)
                       │                                    │
                       no                                   no → SKIP
                       │
                       ▼
                 npm i -g (install)

Skip conditions:

Phase 2: Register & Configure

One pass: use Phase 1 state (do NOT re-run claude mcp list) → remove deprecated → register missing → verify.

1. Reuse Phase 1 state — server map from Step 1a already has registration + connection status
   • Fallback (standalone only): read ~/.claude.json + ~/.claude/settings.json
2. Remove deprecated servers:

3. Register missing servers:
   • IF already configured AND connected → SKIP
   • IF dry_run: true → show planned command
   • IF linear → ask user: "Do you use Linear?" → no → SKIP

Registration commands:

4. Verify: claude mcp list → check all registered show Connected. This is the only second claude mcp list call (post-mutation verify). Retry + report failures.

Error handling:

Phase 3: Hooks & 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: Response must contain Hooks configured for. If SKIPPED, UNKNOWN_AGENT, Error, or failed — STOP.

Phase 4: 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

Skip if hex-graph not registered or not connected.

Phase 5: Migrate allowed-tools [CRITICAL]

Scan project commands/skills to replace built-in tools with hex-line equivalents in allowed-tools frontmatter.

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
4. Write back updated frontmatter (preserve quoting style)

Skip conditions:

Phase 6: Update Instruction Files [CRITICAL]

Ensure instruction files have MCP Tool Preferences section.

MANDATORY READ: Load mcp/hex-line-mcp/output-style.md → use its # MCP Tool Preferences section as template.

Steps:

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 → insert before ## Navigation (or at end of conventions/rules block)
4. If PRESENT but OUTDATED → update table rows to match template
5. For GEMINI.md: adapt tool names (Read → read_file, Edit → edit_file, Grep → search_files)

Skip conditions:

Phase 7: 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)

Idempotent: existing entries skipped.

Phase 8: Report + Benchmark

Status table:

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           |

Token efficiency benchmark:

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

Key metrics: outline vs full read savings, compact diff savings, hash overhead, break-even point.

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. Global install only. Always npm i -g for hex MCP — hooks need stable absolute paths
5. Remove deprecated servers. Clean up servers no longer in the registry
6. Grant permissions. After registration, add mcp__{server} to user settings
7. Minimize claude mcp list calls. Phase 1 runs it once (discovery). Phase 2 reuses that data. Only Phase 2 Step 4 runs it again (post-mutation verify). Max 2 calls total

Anti-Patterns

Definition of Done

• MCP packages installed and versions verified (Phase 1)
• Missing servers registered and verified connected (Phase 2)
• Hooks installed (PreToolUse, PostToolUse, SessionStart) and disableAllHooks: false (Phase 3)
• Output style installed (Phase 3)
• Permissions granted for all configured servers (Phase 7)
• Project allowed-tools migrated (Phase 5)
• MCP Tool Preferences in all instruction files (Phase 6)
• Status table displayed (Phase 8)
• Token efficiency benchmark run (Phase 8)

Version: 1.2.0 Last Updated: 2026-03-23