Skip to content
Forge Docs

Set Up Forge with Claude Code

import { Aside, Tabs, TabItem } from ‘@astrojs/starlight/components’;

Claude Code supports MCP servers out of the box. Forge runs as a local MCP server over stdin/stdout — no daemon, no cloud dependency. Once configured, all 21 Forge tools appear in Claude Code’s tool list and Forge injects its own behavioral instructions at the start of every session.

Prerequisites

Section titled “Prerequisites”
  • Forge installed and on your PATH (forge --version returns a version string)
  • At least one repo indexed (forge index /path/to/repo)
  • Claude Code installed

If you haven’t installed Forge yet, see Install Forge.

Add Forge to .mcp.json

Section titled “Add Forge to .mcp.json”

Create .mcp.json in the root of the repo you want to analyze:

{
  "mcpServers": {
    "forge": {
      "command": "forge",
      "args": ["serve", ".", "--watch"],
      "env": {}
    }
  }
}

Claude Code resolves . relative to where .mcp.json lives — the project root. This is the recommended setup: one .mcp.json per repo, committed alongside the code.

To make Forge available in every Claude Code session regardless of project, add it to ~/.claude/.mcp.json:

{
  "mcpServers": {
    "forge": {
      "command": "forge",
      "args": ["serve", "/absolute/path/to/your/repo", "--watch"],
      "env": {}
    }
  }
}

Use an absolute path here. User-global config loads before Claude Code knows which project it’s in, so . won’t resolve consistently.

Register each repo as a separate server with a unique key:

{
  "mcpServers": {
    "forge-frontend": {
      "command": "forge",
      "args": ["serve", "/home/you/repos/frontend", "--watch"],
      "env": {}
    },
    "forge-backend": {
      "command": "forge",
      "args": ["serve", "/home/you/repos/backend", "--watch"],
      "env": {}
    }
  }
}

Each forge serve process is independent. Tools from both servers appear in Claude Code’s tool list.

Restart Claude Code

Section titled “Restart Claude Code”

After editing .mcp.json, restart Claude Code. MCP server configs load at session start — a running session won’t pick up changes.

Verify the connection

Section titled “Verify the connection”

In a new Claude Code session, ask:

What tools do you have from forge?

Expected response (abbreviated):

From the forge MCP server, I have 21 tools:


Workflow tools:
- forge_prepare: Pre-modification analysis — dependents, health, git activity, GO/CAUTION/STOP
- forge_validate: Post-modification check — verify changes didn't break anything
- forge_understand: Deep comprehension of a file or symbol


Search tools:
- forge_search: Full-text keyword search
- forge_pattern_search: AST structural pattern search (ast-grep syntax)
- forge_search_symbols: Symbol name search


Graph tools:
- forge_trace_imports: Outbound imports from a file
- forge_trace_dependents: Inbound dependents of a file
- forge_check_wiring: Is this module reachable from an entry point?
- forge_find_cycles: Detect circular dependency chains
- forge_dependency_graph: Full dependency graph for a path


... (and 10 more)

If you see this, Forge is connected and ready.

How Forge changes Claude’s behavior

Section titled “How Forge changes Claude’s behavior”

When Claude Code connects to Forge, Forge injects behavioral instructions into the session’s system prompt. These instructions teach Claude Code to:

  • Call forge_prepare before modifying any file
  • Call forge_validate after edits complete
  • Use forge_understand when encountering unfamiliar code
  • Use graph tools (forge_trace_dependents, forge_trace_imports) for targeted dependency lookups

You don’t need to prompt this behavior — it’s automatic from the MCP handshake.

Common pitfalls

Section titled “Common pitfalls”

forge command not found when Claude Code starts Claude Code inherits the PATH from the shell that launched it, not your interactive shell. If you installed Forge to ~/.local/bin and your GUI launcher doesn’t source ~/.bashrc, use the absolute path in the config:

"args": ["/home/you/.local/bin/forge", "serve", ".", "--watch"]

Wait — that should be in "command", not "args". Use:

"command": "/home/you/.local/bin/forge"

Tools appear but return “index not found” The repo path in args doesn’t match where forge index ran. Run forge index . in the repo root, then restart.

Session starts but no Forge tools appear The MCP server failed to start. Check Claude Code’s MCP logs (View → Output → MCP). The most common cause is forge not found on PATH — see above.

Section titled “Related guides”