/configure:mcp

Check and configure Model Context Protocol (MCP) servers for this project.

MCP Philosophy: Servers are managed project-by-project (in .mcp.json), not user-scoped (in ~/.claude/settings.json), to keep context clean and dependencies explicit.

For server configurations, environment variable reference, and report templates, see REFERENCE.md.

When to Use This Skill

| Use this skill when... | Use another approach when... | |------------------------|------------------------------| | Setting up MCP servers for a project | Configuring user-level settings (edit ~/.claude/settings.json directly) | | Checking MCP server status and validating configuration | Just viewing .mcp.json contents (use Read tool) | | Adding specific servers (context7, playwright, sequential-thinking, etc.) | Installing npm/bun packages for non-MCP purposes (use package manager) | | Ensuring team-shareable MCP setups | Personal-only MCP configuration (use ~/.claude/settings.json) | | Installing core productivity servers | Debugging specific server runtime issues (check server logs, restart Claude Code) |

Context

• Config exists: !find . -maxdepth 1 -name \'.mcp.json\'
• Installed servers: !jq -r '.mcpServers' .mcp.json
• Git tracking: !grep '.mcp.json' .gitignore
• Standards file: !find . -maxdepth 1 -name \'.project-standards.yaml\'
• Has playwright config: !find . -maxdepth 1 -name 'playwright.config.*' -print -quit
• Has TS/JS files: !find . -maxdepth 2 \( -name '*.ts' -o -name '*.py' -o -name '*.go' -o -name '*.rs' \) -print -quit
• Dotfiles registry: !find . -maxdepth 1 -name \'~/.local/share/chezmoi/.chezmoidata.toml\'

Parameters

Parse these from $ARGUMENTS:

• --check-only: Report current status, do not offer installation
• --fix: Install servers without prompting for confirmation
• --core: Install all core servers (context7, sequential-thinking)
• --server <name>: Install specific server by name (repeatable)

If no flags provided, run interactive mode (detect → report → offer to install).

Core Servers

These servers should be installed in all projects:

| Server | Purpose | Env Vars | |--------|---------|----------| | context7 | Documentation context from Upstash | None | | sequential-thinking | Enhanced reasoning and planning | None |

Execution

Execute this MCP configuration workflow:

Step 1: Detect current state

Check the context values above. Determine:

1. Does .mcp.json exist? If yes, parse it and list all configured servers.
2. For each server, check its command type (npx, bunx, uvx, go run) and required env vars.
3. Flag any servers with missing required environment variables.

If --check-only, skip to Step 4 (report only).

Step 2: Identify servers to install

Based on the flags:

• --core: Select context7 and sequential-thinking.
• --server <name>: Select the named server(s). Validate against the available servers in REFERENCE.md.
• No flags (interactive): Show the user what's installed vs available. Use AskUserQuestion to ask which servers to add. Suggest servers based on project context (e.g., suggest playwright if playwright.config.* exists, suggest cclsp if large TS/Python/Rust codebase).

If all requested servers are already installed, report "All servers already configured" and stop.

Step 3: Install selected servers

For each selected server:

1. Get the server configuration from REFERENCE.md.
2. If .mcp.json doesn't exist, create it with {"mcpServers": {}}.
3. Merge the server config into the existing mcpServers object. Preserve existing servers.
4. Write the updated .mcp.json with proper JSON formatting.

If cclsp is selected, also set up cclsp.json (see REFERENCE.md for language detection and setup details).

Handle git tracking:

• Check if .mcp.json is in .gitignore.
• If not tracked and not ignored, recommend adding to .gitignore for personal projects or tracking for team projects.

Step 4: Report results

Print a summary using the report format from REFERENCE.md:

• List all configured servers with their status
• Flag missing environment variables with where to set them
• Show git tracking status
• If servers were added, show next steps (restart Claude Code, set env vars)

Step 5: Update standards tracking

If .project-standards.yaml exists, update the MCP section with current server list and timestamp.

Runtime Server Management

After configuring .mcp.json, use these /mcp commands in Claude Code to manage servers without editing files:

| Command | Description | |---------|-------------| | /mcp | List all configured servers and connection status | | /mcp enable <server> | Enable a server for the current session | | /mcp disable <server> | Disable a server for the current session (session-scoped) |

Note: Enable/disable are session-scoped only. Permanent changes require editing .mcp.json.

Agentic Optimizations

| Context | Command | |---------|---------| | Quick status check | jq -c '.mcpServers \| keys' .mcp.json 2>/dev/null | | Validate JSON syntax | jq empty .mcp.json 2>&1 | | List environment variables needed | jq -r '.mcpServers[] \| .env // {} \| keys[]' .mcp.json 2>/dev/null \| sort -u | | Check if server installed | jq -e '.mcpServers.context7' .mcp.json >/dev/null 2>&1 && echo "installed" \|\| echo "missing" | | Core servers install (automated) | /configure:mcp --core --fix | | Specific server install (automated) | /configure:mcp --server context7 --fix | | Check-only mode (CI/reporting) | /configure:mcp --check-only |

Flags

| Flag | Description | |------|-------------| | --check-only | Report status without offering to install servers | | --fix | Install specified or suggested servers without prompting | | --core | Install all core servers (context7, sequential-thinking) | | --server <name> | Install specific server (can be repeated) |

Error Handling

• Invalid .mcp.json: Offer to backup and replace with valid template
• Server already installed: Skip with informational message
• Missing env var: Warn but continue (server may work with defaults)
• Unknown server: Report error with available server names