git:20260321.b53274d to git:20260405.f115d49

---

name: mcp-add

description: Install an MCP server template from claude-kit into a project or global Claude Code config with a single command.

---

# MCP Add

Install a claude-kit MCP server template into the current project's or global Claude Code configuration.

## Input parsing

From `$ARGUMENTS` (format: `mcp add <server> [--global]`):

- Extract `<server>`: the word after `mcp add` — one of `github`, `postgres`, `supabase`, `redis`, `slack`

- Detect `--global` flag: if present, target `~/.claude/settings.json`; otherwise target `.claude/settings.json`

## Step 0: Validate

1. Verify the server template exists: `$CLAUDE_KIT_DIR/mcp/<server>/`

- If directory not found:

```

✗ Unknown server '{{server}}'.

Available: github, postgres, supabase, redis, slack

Usage: /forge mcp add <server> [--global]

```

Stop.

2. Determine target settings path:

- `--global` → `~/.claude/settings.json`

- default → `.claude/settings.json`

- If target doesn't exist and not `--global`: warn "No settings.json found. Run `/forge bootstrap` first, or use `--global` to install globally." Stop.

- If target doesn't exist and `--global`: create `~/.claude/settings.json` with `{"permissions": {"allow": [], "deny": []}, "mcpServers": {}}`.

## Step 1: Load template files

Read all three template files:

- `$CLAUDE_KIT_DIR/mcp/<server>/config.json`

- `$CLAUDE_KIT_DIR/mcp/<server>/permissions.json`

- `$CLAUDE_KIT_DIR/mcp/<server>/rules.md`

From `config.json`:

- **Server key**: the non-metadata top-level key (e.g., `"github"`, `"postgres"`)

- **Server config block**: the value of that key (the object with `type`, `command`, `args`, `env`)

- **Install note**: the `_install` string — contains required env vars and instructions

- Ignore all keys starting with `_` (metadata)

From `permissions.json`:

- **allow**: the `allow` array value (or `[]` if absent)

- **deny**: the `deny` array value (or `[]` if absent)

- Ignore all keys starting with `_`

## Step 2: Check for existing configuration

Read the target `settings.json`.

Check if the server is already configured:

- Present if `mcpServers.<server>` key exists in settings, OR

- Present if any of the server's allow entries appear in `permissions.allow`

If already configured:

```

```

## Step 3: Show preview

```

══════════════════════════════════════════

MCP Add: {{SERVER}} → {{target path}}

══════════════════════════════════════════

mcpServers.{{server}}:

{{pretty-print the server config block, replacing env var values like "${GITHUB_TOKEN}"

with the literal placeholder strings — do not expand env vars}}

Rules:

$CLAUDE_KIT_DIR/mcp/{{server}}/rules.md

→ {{rules destination}}

{{_install text from config.json}}

```

If no new denies to add, omit that line.

## Step 4: Apply changes

### 4a. Merge mcpServers

Read target `settings.json` as JSON.

Set `settings["mcpServers"]["{{server}}"]` = the server config block.

If `mcpServers` key doesn't exist in settings, create it.

### 4b. Merge permissions

**Allow list:**

- For each entry in template `allow[]`: add to `settings.permissions.allow` only if not already present

- Never remove or reorder existing entries

**Deny list:**

- For each entry in template `deny[]`: add to `settings.permissions.deny` only if not already present

- Never remove or reorder existing entries

If `settings.permissions` doesn't exist, create it with `{"allow": [], "deny": []}`.

### 4c. Write settings.json

Write the modified settings.json with 2-space indentation. Preserve all other existing keys

(hooks, autoMemoryEnabled, env, etc.) exactly as they were.

### 4d. Copy rules.md

Determine rules destination:

- Project mode: `.claude/rules/mcp-{{server}}.md`

- Global mode: `~/.claude/rules/mcp-{{server}}.md`

Copy `$CLAUDE_KIT_DIR/mcp/{{server}}/rules.md` to the destination.

If the file already exists: overwrite — it's a managed template file. Any project-specific

customizations should live in a separate rule file, not in `mcp-{{server}}.md`.

Create the destination directory if it doesn't exist.

## Step 5: Confirm result

```

{{_install text from config.json}}

```

If global install:

If project-only install: