Paths: File paths (references/) are relative to this skill directory.

MCP Configurator

Type: L3 Worker Category: 0XX Shared

Invocation is agent-agnostic. Target surfaces are Claude-specific: this skill configures Claude Code MCP settings, hook/style sync, permissions, and Claude Code IDE extension permission mode.

MANDATORY READ

MANDATORY READ: Load references/coordinator_summary_contract.md, references/environment_worker_runtime_contract.md, and references/worker_runtime_contract.md

Target MCP availability is not a precondition for this worker. If a server is not connected yet, use config files, package metadata, and CLI state to continue registration and cleanup work; report provider checks or live verification as skipped when they cannot run without MCP.

Input / Output

If summaryArtifactPath is provided, write the same summary JSON there. If not provided, return the summary inline and remain fully standalone. If runId is not provided, generate a standalone run_id before emitting the summary envelope.

Runtime

Runtime family: environment-worker-runtime

Phase profile:

1. PHASE_0_CONFIG
2. PHASE_1_CHECK_STATUS_AND_VERSION
3. PHASE_2_REGISTER_AND_CONFIGURE
4. PHASE_3_VERIFY_GRAPH_PROVIDER_DEPS
5. PHASE_4_HOOKS_AND_OUTPUT_STYLE
6. PHASE_5_GRAPH_INDEXING
7. PHASE_6_MIGRATE_ALLOWED_TOOLS
8. PHASE_7_PERMISSION_SURFACES
9. PHASE_8_WRITE_SUMMARY
10. PHASE_9_SELF_CHECK

Runtime rules:

• emit summary_kind=env-mcp-config
• standalone runs generate their own run_id and write the default worker-family artifact path
• managed runs require both runId and summaryArtifactPath and must write the summary to the exact provided path
• always write the validated summary artifact before terminal outcome

Output Contract

Always build a structured env-mcp-config summary envelope per:

• references/coordinator_summary_contract.md
• references/environment_worker_runtime_contract.md

Payload fields:

• servers
• permissions
• ide_extension
• hooks_synced
• output_style_synced
• allowed_tools_migrated
• graph_provider_status
• status

Server Registry

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

Workflow

Check Status & Version → Register & Configure → Verify Graph Provider Deps → Hooks → Permissions → IDE Extension Mode → Migrate → Report

Phase 1: Check Status & Version

Smart install: check MCP status AND package drift. npx -y caches aggressively — a connected server may still be backed by an older cached package.

Step 1a: Check MCP server status

Run claude mcp list -> parse each hex server:

Step 1b: Version check for connected hex- servers*

For each connected published hex server, run in parallel:

npm view @levnikolaevich/${PKG} version 2>/dev/null

Then compare npm latest against the running local version:

1. npx cache probe: npm config get cache -> scan {cacheRoot}/_npx/**/node_modules/@levnikolaevich/${PKG}/package.json -> pick newest by semver/mtime

Use the npx cache version. If probe returns nothing, report running=unknown and treat the server as refresh-recommended rather than claiming it is current.

Note: published hex packages run via npx -y, NOT global install. Never probe global npm paths.

Skip conditions:

Phase 2: Register & Configure

One pass: use Phase 1 state (do NOT re-run claude mcp list) -> remove unsupported -> register/update -> 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 unsupported servers:

3. Register missing OR update outdated servers:
   • IF already configured AND connected AND cached local version matches -> SKIP
   • IF connected but outdated -> remove + re-add (forces npx to fetch latest)
   • IF dry_run: true -> show planned command
   • IF linear -> ask user: "Do you use Linear?" -> no -> SKIP

Registration commands (OS-dependent prefix):

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.

Windows MSYS2 path validation (MANDATORY on win32): After registration, read ~/.claude.json -> verify each hex server's args[0] is "/c" not "C:/". If corrupted: fix via mcp__hex-line__edit_file (set_line the arg to "/c").

Error handling:

Phase 2b: Verify Graph Provider Depend