Skill: drumrobot/mcp-config (version 0.1.2)

--- name: mcp-config metadata: author: es6kr version: "0.1.2" description: | MCP server configuration and diagnostics. add - add server (scope selection + registration) [add.md], move - change server scope (project→local, local→user) [move.md], format - JSON format reference (differences per agent) [format.md], catalog - list of commonly used servers [catalog.md], diagnostics - connection failure diagnosis and troubleshooting [diagnostics.md]. Use when: "add MCP", "mcp-config", "MCP server config", "add context7", "MCP format", "MCP server list", "move MCP", "MCP scope", "scope change", "MCP connection failed", "MCP error", "Failed to reconnect", "code-mode not working", "MCP server issue". --- # MCP Server Configuration Correctly add and manage MCP servers in the `.mcp.json` file. ## Topics | Topic | Description | Guide | |-------|-------------|-------| | add | Add server (scope selection + registration + validation) | [add.md](./add.md) | | catalog | Catalog of commonly used MCP servers | [catalog.md](./catalog.md) | | diagnostics | Connection failure diagnosis and troubleshooting | [diagnostics.md](./diagnostics.md) | | format | JSON format reference (differences per agent) | [format.md](./format.md) | | move | Change server scope (project→local, local→user) | [move.md](./move.md) | ## Quick Reference ``` "add MCP" → add topic (scope selection → registration) "add context7" → add topic + refer to catalog for config "move MCP" → move topic (scope change: remove + re-add) "MCP format" → format topic (JSON differences per agent) "MCP server list" → catalog topic "MCP connection failed" → diagnostics topic (connection troubleshooting) "Failed to reconnect" → diagnostics topic ``` ## Core Rules - **New MCP server = register as a separate key** (do not put inside an existing server's `env`) - **Scope selection AskUserQuestion required** (global vs project, agent selection) - **Antigravity requires `transport: "stdio"`**

path: add.md
content: # Add MCP Server

Procedure for registering a new MCP server.

## CRITICAL: Claude Code uses `claude mcp add` CLI

**Do NOT manually edit `.mcp.json` for Claude Code.** Manually adding entries to `.mcp.json` does NOT make Claude Code recognize the server. Always use the `claude mcp add` CLI command.

```bash
# stdio server (project scope)
claude mcp add --scope project my-server -- npx my-mcp-server

# HTTP server (project scope)
claude mcp add --transport http --scope project my-server https://example.com/mcp

# stdio server with env vars
claude mcp add --scope project -e API_KEY=xxx my-server -- npx my-mcp-server
```

**Name restriction**: Only letters, numbers, hyphens, underscores. No spaces.

## Required Procedure: Scope Selection (AskUserQuestion Required)

**Before adding an MCP server, always use AskUserQuestion in 2 steps:**

### Step 1: Scope Selection

| Option | Description |
|--------|-------------|
| Global | Add to each agent's config file (proceed to step 2) |
| Project | Add only to the current project |

### Step 2: When Global is selected → Agent Selection (multiSelect)

| Agent | Method | Difference |
|-------|--------|------------|
| Claude Code | `claude mcp add --scope user` | CLI required, manual `.mcp.json` edit NOT recognized |
| Cursor | Edit `~/.cursor/mcp.json` | `transport` field not required |
| Antigravity | Edit `~/.gemini/antigravity/mcp_config.json` | `"transport": "stdio"` required |

**multiSelect: true** — can add to multiple agents simultaneously.

**Do not decide arbitrarily.** Even if `.mcp.json` exists in the project directory, the user may want to add globally, and vice versa.

### Claude Code Scope Options

| Scope | Flag | Config File | Key Path | Description |
|-------|------|-------------|----------|-------------|
| local | `--scope local` (default) | `~/.claude.json` | `projects["/path/to/project"].mcpServers` | This machine, this project only |
| user | `--scope user` | `~/.claude.json` | root `mcpServers` | This machine, all projects |
| project | `--scope project` | `./.mcp.json` | `mcpServers` | Committed to repo, shared with team |

## Core Rule: Register as Separate Server

New MCP server = register as a separate key. **Do not put it inside an existing server's `env`.**

## Validation Checklist

- [ ] Claude Code: used `claude mcp add` CLI (NOT manual `.mcp.json` edit)
- [ ] Cursor/Antigravity: JSON syntax is valid
- [ ] Each server is registered as a separate key
- [ ] Server name contains only letters, numbers, hyphens, underscores
- [ ] `claude mcp list` shows the server as Connected


path: catalog.md
content: # MCP Server Catalog

List of commonly used MCP servers.

## Server List

| Server | Package | Command | Purpose |
|--------|---------|---------|---------|
| code-mode | `@utcp/code-mode-mcp` | npx | UTCP tool chain |
| context7 | `@upstash/context7-mcp` | npx | Library documentation search |
| playwright | `@anthropics/mcp-playwright` | npx | Browser automation |
| postgres | `postgres-mcp` | uvx | PostgreSQL database |

## Configuration Examples per Server

### code-mode

```json
{
  "code-mode": {
    "command": "npx",
    "args": ["-y", "@utcp/code-mode-mcp"],
    "env": {
      "UTCP_CONFIG_FILE": "~/.utcp_config.json"
    }
  }
}
```

### context7

```json
{
  "context7": {
    "command": "npx",
    "args": ["-y", "@upstash/context7-mcp"]
  }
}
```

### playwright

```json
{
  "playwright": {
    "command": "npx",
    "args": ["-y", "@anthropics/mcp-playwright"]
  }
}
```

### postgres

```json
{
  "postgres": {
    "command": "uvx",
    "args": ["postgres-mcp", "--access-mode=unrestricted"],
    "env": {
      "DATABASE_URI": "postgresql://user:pass@host:5432/db"
    }
  }
}
```


path: diagnostics.md
content: # MCP Server Connection Diagnostics

Diagnose and resolve MCP server connection issues.

## Diagnostic Steps

### 1. Quick Status Check (Start Here)

```bash
# List all MCP servers and their connection status
claude mcp list
```

If the server appears as **Disconnected** or is missing entirely, proceed to Step 2.

### 2. Verify Configuration Files (Check ALL in order)

| Priority | File | Description |
|----------|------|-------------|
| 1 | `~/.claude.json` | **Claude Code global MCP config** (mcpServers section) |
| 2 | `~/.claude/settings.json` | Claude Code settings mcpServers |
| 3 | `~/.claude/settings.local.json` | Local overrides |
| 4 | `.mcp.json` (project root) | Project-level MCP config |
| 5 | `~/.config/claude/mcp.json` | User-level (legacy) |
| 6 | `~/.utcp_config.json` | UTCP-specific config |
| 7 | Plugin cache (`~/.claude/plugins/cache/`) | MCP servers provided by plugins |

**Always check `~/.claude.json` first** — this is the primary file where Claude Code stores MCP server configurations.

### 3. Common Errors and Solutions

#### "Connection closed" / "MCP error -32000"

**Cause**: Server process exits immediately after starting.

**Check**:
- Command path is correct (`which npx`, `which node`)
- Environment variables are set
- Native module build failures

#### "Failed to reconnect to [server-name]"

**Cause**: Previously connected server is no longer responding.

**Resolution**:
1. Check server status with `/mcp` command
2. Restart server or verify configuration

#### UTCP code-mode Specific Issues

**isolated-vm build failure**:
- Node.js version compatibility (LTS 22.x recommended)
- No prebuilt binaries for arm64 macOS
- Fix: `asdf local nodejs 22.14.0` then reinstall

**Empty config file**:
- If `~/.utcp_config.json` is `{}`, initialization failed
- Minimum required config:
```json
{
  "load_variables_from": [],
  "manual_call_templates": [],
  "tool_repository": {
    "tool_repository_type": "in_memory"
  },
  "tool_search_strategy": {
    "tool_search_strategy_type": "tag_and_description_word_match"
  },
  "post_processing": []
}
```

### 4. Check Logs

```bash
# Latest MCP debug logs (UUID-based filenames)
ls -lt ~/.claude/debug/ | head -5

# Read a specific log
cat ~/.claude/debug/<uuid>.txt
```

### 5. Manual Server Test

Run the server command directly outside Claude Code to see raw errors:

```bash
# npx-based server
npx -y @utcp/code-mode-mcp

# npx with environment variables
UTCP_CONFIG_FILE=~/.utcp_config.json npx -y @utcp/code-mode-mcp

# uvx-based server (e.g., serena, postgres)
uvx --from "git+https://github.com/oraios/serena" serena start-mcp-server --context claude-code
```

**Key**: Copy the exact `command` + `args` from `~/.claude.json` and run it in your terminal. The error output will reveal the root cause (missing dependency, wrong argument, auth failure, etc.).


path: format.md
content: # MCP Server Format

JSON format reference per agent.

## File Locations

| Agent | File | Key Path | Scope | Method |
|-------|------|----------|-------|--------|
| Claude Code (local) | `~/.claude.json` | `projects[path].mcpServers` | This machine, this project | `claude mcp add --scope local` (default) |
| Claude Code (user) | `~/.claude.json` | root `mcpServers` | This machine, all projects | `claude mcp add --scope user` |
| Claude Code (project) | `./.mcp.json` | `mcpServers` | Committed to repo, shared with team | `claude mcp add --scope project` |
| Cursor | `~/.cursor/mcp.json` | Global | Manual edit |
| Antigravity | `~/.gemini/antigravity/mcp_config.json` | Global | Manual edit |

**IMPORTANT**: Claude Code requires `claude mcp add` CLI. Manual `.mcp.json` edits are NOT recognized.

## Basic Format

```json
{
  "server-name": {
    "command": "npx",
    "args": ["-y", "@package/name"]
  }
}
```

## When Environment Variables Are Required

```json
{
  "server-name": {
    "command": "npx",
    "args": ["-y", "@package/name"],
    "env": {
      "API_KEY": "${API_KEY}",
      "CONFIG_FILE": "~/.config/file.json"
    }
  }
}
```

## Using uvx (Python Packages)

```json
{
  "postgres": {
    "command": "uvx",
    "args": ["postgres-mcp", "--access-mode=unrestricted"],
    "env": {
      "DATABASE_URI": "postgresql://user:pass@host:5432/db"
    }
  }
}
```

## Antigravity Format Difference

Antigravity requires the `transport` field:

```json
{
  "server-name": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@package/name"]
  }
}
```

Claude Code / Cursor do not require `transport`.


path: move.md
content: # Move MCP Server (Scope Change)

Change an existing MCP server's scope (e.g., project → local, local → user).

## CRITICAL: Claude Code uses CLI only

Scope change = **remove from old scope** + **add to new scope**. Both steps use `claude mcp` CLI.

## Procedure

### 1. Identify current scope

```bash
claude mcp list
```

Find the server and note its current scope (local/user/project).

### 2. Capture server config

```bash
claude mcp get <server-name>
```

Record: command, args, env vars, transport type.

### 3. Remove from old scope

```bash
claude mcp remove --scope <old-scope> <server-name>
```

### 4. Add to new scope

```bash
# stdio server
claude mcp add --scope <new-scope> <server-name> -- <command> [args...]

# stdio server with env vars
claude mcp add --scope <new-scope> -e KEY=val <server-name> -- <command> [args...]

# HTTP server
claude mcp add --transport http --scope <new-scope> <server-name> <url>
```

### 5. Verify

```bash
claude mcp list
```

Confirm the server appears under the new scope and shows as Connected.

## Scope Reference

| Scope | Flag | Description |
|-------|------|-------------|
| local | `--scope local` | This machine, this project only (default) |
| user | `--scope user` | This machine, all projects |
| project | `--scope project` | `.mcp.json`, committed to repo |

## Special: Project scope (.mcp.json) removal

When removing from **project** scope, `claude mcp remove --scope project` edits `.mcp.json`.
Alternatively, you can manually edit `.mcp.json` to remove the entry (project scope is the only scope where manual edit is acceptable for removal).

## When to Move: Scope Selection Guidelines

| Condition | Recommended Scope | Reason |
|-----------|-------------------|--------|
| Server uses absolute local paths (e.g., `/Users/es6kr/...`) | **local** | Path is machine+project specific, not portable to other machines or projects |
| Server uses relative paths or npx | **project** | Portable, can be committed to git for team sharing |
| Server needed across all projects on this machine | **user** | Global availability without per-project config |
| Server contains secrets in env vars | **local** or **user** | Avoid committing secrets to `.mcp.json` in git |

**Key rule**: If a server config contains machine-specific absolute paths, it should NOT be in project scope (`.mcp.json`) — it will break for other contributors or on other machines.

## Examples

```bash
# Move from project to local
claude mcp remove --scope project my-server
claude mcp add --scope local my-server -- node /path/to/server.js

# Move from local to user (all projects)
claude mcp remove --scope local my-server
claude mcp add --scope user my-server -- npx my-mcp-server
```


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)