| name | mcp-add |
| description | Install an MCP server template from dotforge into a project or global Claude Code config with a single command. |
MCP Add
Install a dotforge 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
-
Verify the server template exists: $DOTFORGE_DIR/mcp/<server>/
- If directory not found:
✗ Unknown server '{{server}}'.
Available: github, postgres, supabase, redis, slack
Usage: /forge mcp add <server> [--global]
Stop.
-
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:
$DOTFORGE_DIR/mcp/<server>/config.json$DOTFORGE_DIR/mcp/<server>/permissions.json$DOTFORGE_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:
⚠ {{server}} MCP is already configured in {{target}}.
Options:
[u] Update — replace mcpServers.{{server}}, add missing permissions (does not remove existing ones)
[q] Quit — make no changes
What would you like to do? [u/Q]
u → continue with update flow (Step 3)Q or anything else → stop
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}}
New permissions:
allow (+{{N}} new): {{list entries not already in target settings}}
deny (+{{N}} new): {{list entries not already in target settings}}
(Existing permissions are not modified)
Rules:
$DOTFORGE_DIR/mcp/{{server}}/rules.md
→ {{rules destination}}
Required environment variables:
{{_install text from config.json}}
Proceed? [Y/n]
If all permissions are already present, show "Permissions: no changes (already configured)".
If no new denies to add, omit that line.
Step 4: Apply changes
Only proceed if user confirms (Y, y, Enter, or "yes").
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 $DOTFORGE_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
✓ {{SERVER}} MCP configured
Updated files:
{{target settings.json}} — mcpServers.{{server}} added
{{rules destination}} — behavior rules copied
{{"+N permissions" if any were added, else "permissions: no changes"}}
Next step:
{{_install text from config.json}}
Restart Claude Code to activate the MCP server.
If global install:
Add: "Installed globally — active in all projects."
If project-only install:
Add: "Installed in the current project. For global use: /forge mcp add {{server}} --global"
