Configure Mcp

/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

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:

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:

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

Agentic Optimizations

Flags

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

MCP Server Reference

Server Configurations

Use these JSON configurations when adding servers to .mcp.json:

{
  "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"
    ]
  },
  "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"]
  },
  "cclsp": {
    "command": "npx",
    "args": ["-y", "cclsp@latest"],
    "env": {
      "CCLSP_CONFIG_PATH": "./cclsp.json"
    }
  }
}

Environment Variable Reference

Use ${VAR_NAME} references in .mcp.json — never hardcode tokens.

Available Servers (Full Registry)

Context & Knowledge:

• context7 - Upstash context management (no env vars)

AI Enhancement:

• sequential-thinking - Enhanced reasoning with sequential thinking (no env vars)

Testing & Automation:

• playwright - Browser automation and testing (no env vars)

Version Control:

• github - GitHub API integration (requires GITHUB_TOKEN)

Productivity:

• pal - PAL (Provider Abstraction Layer) - Multi-provider LLM integration (no env vars)

Infrastructure & Monitoring:

• argocd-mcp - ArgoCD GitOps deployment management (requires ARGOCD_SERVER, ARGOCD_AUTH_TOKEN)
• sentry - Sentry error tracking and monitoring (requires SENTRY_AUTH_TOKEN)

Code Intelligence (optional):

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

cclsp Setup Details

When installing cclsp, create cclsp.json in the project root with language servers based on detected project files:

Write cclsp.json with detected servers:

{
  "servers": [
    // entries based on detected languages
  ]
}

Add cclsp.json to .gitignore (machine-specific language server paths).

Required language server installations:

• TypeScript: npm i -g typescript-language-server
• Python: pip install python-lsp-server
• Go: go install golang.org/x/tools/gopls@latest
• Rust: Install via rustup component add rust-analyzer

Report Templates

Compliance Report Format

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]

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

Overall: [X issues found]

Completion Report Format

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)

Remote MCP Servers (HTTP+SSE with OAuth)

For remote servers using HTTP+SSE transport (Claude Code 2.1.50+):

{
  "my-remote-server": {
    "url": "https://mcp.example.com/sse",
    "headers": {
      "Authorization": "Bearer ${MY_API_TOKEN}"
    }
  }
}

OAuth Authentication Flow

1. Claude Code discovers OAuth metadata from /.well-known/oauth-authorization-server (cached per server URL) 2. User authorizes in the browser on first use 3. Token is persisted and reused across sessions 4. Step-up auth triggered mid-session when a tool requires additional scopes

Remote Server Notes

• Use ${VAR_NAME} in header values — never hardcode tokens
• Discovery metadata is cached; use /mcp disable + /mcp enable to force refresh
• Remote servers using OAuth do not need env block; use headers with Bearer token instead
• Step-up auth is automatic — Claude Code handles re-authorization prompts

Standards Tracking Template

Update .project-standards.yaml:

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