Connect to Claude Code

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

Forge speaks the Model Context Protocol (MCP) over stdin/stdout. Any MCP-compatible AI agent can connect to it. This guide covers Claude Code — the most common setup.

Add Forge to `.mcp.json`

Claude Code looks for MCP servers in .mcp.json in your project root (project-local) or in ~/.claude/.mcp.json (user-global, applies to all projects).

Create .mcp.json in the root of the repo you indexed:

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

This config serves the current directory (.). Claude Code resolves . relative to the project root where .mcp.json lives.

If you want Forge available in every Claude Code session, add it to ~/.claude/.mcp.json:

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

Use the absolute path to the repo when setting up user-global config — . won’t resolve consistently from different working directories.

Add --watch to have Forge auto-update the index when files change. Useful during active development:

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

--watch adds a small background process. Skip it for large repos (100K+ files) where the file watcher overhead may be noticeable.

Restart Claude Code

After editing .mcp.json, restart Claude Code for the new server config to take effect. Claude Code loads MCP server configs at session start.

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 (use these first):
- 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 — full structural analysis 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 Claude Code doesn’t list Forge tools, see Troubleshooting: MCP server won’t start.

How Forge sends its own instructions

When Claude Code connects, Forge injects behavioral instructions into the session’s system prompt automatically. This teaches Claude Code:

Call forge_prepare before modifying any file
Call forge_validate after modifications complete
Use forge_understand for unfamiliar code before making plans
Use search and graph tools for targeted lookups

You don’t need to prompt Claude Code to use these patterns — Forge’s server instructions set this behavior up automatically at the MCP handshake.

Other agents

For setup with other MCP-compatible clients, see the How-To Guides:

The MCP connection pattern is the same across all clients — only the config file location differs. See Concepts: MCP Protocol for details.

Your first workflow — use forge_prepare before asking Claude to refactor something.