MCP Server Won't Start

Symptoms

• Your MCP client (Claude, Cursor, etc.) reports it cannot connect to Forge.
• Error messages such as “failed to start MCP server”, “spawn failed”, or “connection refused”.
• The client connects but all tool calls return empty results or errors.
• forge serve starts from the command line but the client still cannot see the tools.

---

Likely Causes

Cause	Indicator
Wrong path to the forge binary in .mcp.json	”spawn failed” or “command not found”
forge binary not in the shell’s PATH	Works from terminal but not from client
Repository has not been indexed yet	Tools call but return “index not found”
.mcp.json points to the wrong repository path	Tools return results for the wrong repo
Community Mode restriction	MCP server refused without license (forge serve exits with an error)

---

Step-by-Step Fix

Step 1: Confirm forge is in your PATH

which forge
forge --version

Expected output:

/usr/local/bin/forge
forge 1.3.0

If which forge returns nothing, see Client Can’t Find forge.

Step 2: Check your .mcp.json configuration

Your MCP client reads server definitions from .mcp.json (or an equivalent config file). A typical Forge entry looks like:

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

Verify:

• "command" is "forge" or an absolute path to the binary (e.g., "/usr/local/bin/forge").
• "args" includes the absolute path to the repository you want to analyze. Relative paths may not resolve correctly depending on how the client launches the server.
• The repository path exists and contains a .git directory.

Step 3: Verify the repository is indexed

The MCP server requires an existing index. Run:

forge status --repo /absolute/path/to/your/repo

If you see “repository not found”, index it first:

forge index /absolute/path/to/your/repo --with-search

Then restart your MCP client.

Step 4: Test the server manually

Run forge serve from the command line to see if it starts cleanly:

forge serve /absolute/path/to/your/repo

Expected output:

forge MCP server started for /absolute/path/to/your/repo
Listening on stdin/stdout (JSON-RPC 2.0)

If you see an error here, the problem is in Forge itself (not the client config). Common errors:

• index not found — run forge index first
• license required — Community Mode: MCP server requires a license (see below)

Step 5: Community Mode restriction

Starting with v1.3.0, forge serve in Community Mode (no license) refuses to start the MCP server. If you see this error, you have two options:

1. Activate a license: Run forge activate <key> or start a trial at https://forge.ironpinelabs.com/pricing.
2. Use CLI commands directly: Community Mode supports forge search, forge health, and forge status from the command line without the MCP server.

Step 6: Use absolute paths

Some MCP clients launch servers from a different working directory than your terminal. Use absolute paths in .mcp.json:

{
  "mcpServers": {
    "forge": {
      "command": "/usr/local/bin/forge",
      "args": ["serve", "/Users/yourname/repos/my-project"]
    }
  }
}

Replace /usr/local/bin/forge with the output of which forge.

Step 7: Restart the MCP client

After any change to .mcp.json or after running forge index, restart your MCP client completely. Most clients do not detect configuration changes dynamically.

---

When to Escalate

Contact support at [email protected] if:

• forge serve <path> starts cleanly from the terminal but the client still cannot connect.
• Tool calls return unexpected errors after the server is confirmed running.

Include the output of:

forge --version
forge status --repo /path/to/repo
forge license