/configure:mcp

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

Context

This command validates MCP server configuration and installs servers from the favorites registry.

MCP Philosophy: Servers are managed project-by-project to avoid context bloat:

• ❌ User-scoped (in ~/.claude/settings.json) – Bloated context everywhere
• ✅ Project-scoped (in .mcp.json) – Clean context, explicit dependencies, team-shareable

Core Servers

These servers should be installed in all projects by default:

Run /configure:mcp --core to install all core servers automatically.

Optional Servers

These servers provide additional capabilities for specific project types:

Note: cclsp provides 6 focused LSP tools without duplicating Claude Code’s built-in file, shell, and search capabilities. Recommended over heavier alternatives for projects that need semantic code navigation.

Workflow

Phase 1: Current State Detection

Check for existing MCP configuration:

Phase 2: Current Configuration Analysis

For existing .mcp.json, analyze:

• File exists and is valid JSON
• mcpServers object present
• Installed servers list
• Environment variable references validated
• Required env vars documented

Currently Installed Servers: List each server with:

• Name
• Command type (npx, bunx, uvx, go run)
• Required environment variables
• Status (✅ configured / ⚠️ missing env var)

Phase 3: Compliance Report

MCP Configuration Report
========================
Project: [name]
Config file: .mcp.json

Installed Servers:
  github                    go run           [✅ CONFIGURED | ⚠️ NEEDS GITHUB_TOKEN]
  playwright                bunx             [✅ CONFIGURED]
  pal                       uvx              [✅ CONFIGURED]
  context7                  bunx             [✅ CONFIGURED]

Environment Variables:
  GITHUB_TOKEN              ~/.api_tokens    [✅ SET | ❌ MISSING]
  ARGOCD_SERVER             project .env     [✅ SET | ❌ MISSING]
  ARGOCD_AUTH_TOKEN         project .env     [✅ SET | ❌ MISSING]

Git Tracking:
  .mcp.json                 .gitignore       [✅ IGNORED | ⚠️ TRACKED | ❌ NOT FOUND]

Overall: [X issues found]

Recommendations:
  - Add 'github' server for GitHub API integration
  - Set GITHUB_TOKEN in ~/.api_tokens
  - Add .mcp.json to .gitignore for personal projects

Phase 4: Available MCP Servers

From dotfiles favorites registry (~/.local/share/chezmoi/.chezmoidata.toml):

Context & Knowledge:

• context7 – Upstash context management

Testing & Automation:

• playwright – Browser automation and testing

Version Control:

• github – GitHub API integration (issues, PRs, repos)

Productivity:

• pal – PAL (Provider Abstraction Layer) – Multi-provider LLM integration
• podio-mcp – Podio project management integration

Infrastructure & Monitoring:

• argocd-mcp – ArgoCD GitOps deployment management
• sentry – Sentry error tracking and monitoring

AI Enhancement:

• sequential-thinking – Enhanced reasoning with sequential thinking

Code Intelligence (optional):

• cclsp – LSP navigation (find-references, go-to-definition, rename) for TS/Python/Rust projects

Phase 5: Configuration (if –fix or user confirms)

Server Configurations

{
  "pal": {
    "command": "uvx",
    "args": [
      "--from",
      "git+https://github.com/BeehiveInnovations/pal-mcp-server.git",
      "pal-mcp-server"
    ]
  },
  "playwright": {
    "command": "bunx",
    "args": ["-y", "@playwright/mcp@latest"]
  },
  "context7": {
    "command": "bunx",
    "args": ["-y", "@upstash/context7-mcp"]
  },
  "github": {
    "command": "go",
    "args": [
      "run",
      "github.com/github/github-mcp-server/cmd/github-mcp-server@latest",
      "stdio"
    ]
  },
  "podio-mcp": {
    "command": "bunx",
    "args": ["https://github.com/ForumViriumHelsinki/podio-mcp"],
    "env": {
      "PODIO_CLIENT_ID": "${PODIO_CLIENT_ID}",
      "PODIO_CLIENT_SECRET": "${PODIO_CLIENT_SECRET}",
      "PODIO_APP_ID": "${PODIO_APP_ID}",
      "PODIO_APP_TOKEN": "${PODIO_APP_TOKEN}"
    }
  },
  "argocd-mcp": {
    "command": "bunx",
    "args": ["-y", "argocd-mcp@latest", "stdio"],
    "env": {
      "ARGOCD_SERVER": "${ARGOCD_SERVER}",
      "ARGOCD_AUTH_TOKEN": "${ARGOCD_AUTH_TOKEN}"
    }
  },
  "sequential-thinking": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
  }
}

Installation Steps

1. Ask which servers to install (unless –server specified):

   • Use AskUserQuestion with multi-select
   • Show descriptions and required env vars
   • Suggest based on project type (e.g., playwright if playwright.config.* exists)

2. Create/update .mcp.json:

   • If missing, create new file with mcpServers object
   • If exists, merge new servers (preserve existing)
   • Use proper JSON formatting

3. Handle environment variables:

   • Document required variables for each server
   • Check if set in ~/.api_tokens or project .env
   • Warn about missing required variables

4. Git tracking recommendation:

   • Personal projects → recommend .gitignore (keep API configs local)
   • Team projects → recommend tracking (share MCP setup with team)

Phase 6: Environment Variable Reference

Never hardcode tokens in .mcp.json – always use ${VAR_NAME} references.

Phase 7: Standards Tracking

Update .project-standards.yaml:

standards_version: "2025.1"
last_configured: "[timestamp]"
components:
  mcp: "2025.1"
  mcp_servers: ["github", "playwright", "context7"]
  mcp_project_scoped: true

Phase 8: Final Report

MCP Configuration Complete
==========================

Servers Added:
  ✅ github (requires GITHUB_TOKEN)
  ✅ playwright
  ✅ context7

Environment Variables:
  ⚠️ Set GITHUB_TOKEN in ~/.api_tokens or project .env

Git Tracking:
  ✅ .mcp.json added to .gitignore

Next Steps:
  1. Restart Claude Code to load new MCP servers
  2. Set required environment variables
  3. Verify servers are loaded (check status bar)

Tip: Run /configure:mcp again to add more servers anytime.

Flags

Examples

# Check current MCP configuration
/configure:mcp --check-only

# Interactive server installation
/configure:mcp

# Install all core servers (recommended for new projects)
/configure:mcp --core

# Install specific servers automatically
/configure:mcp --fix --server github --server playwright

# Quick add github server
/configure:mcp --server github

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 don’t fail (server may work with defaults)
• Unknown server: Error with suggestion to check registry

See Also

• /configure:all – Run all compliance checks
• MCP Management skill – Intelligent server suggestions based on project
• Dotfiles registry: ~/.local/share/chezmoi/.chezmoidata.toml