forgeplan serve

Start the Forgeplan MCP (Model Context Protocol) server on stdio. This is the primary integration point for AI agents — Claude Code, Cursor, Windsurf, and other MCP clients launch forgeplan serve as a subprocess and talk to it over JSON-RPC on stdin/stdout.

Usage

forgeplan serve

Options

  -h, --help     Print help
  -V, --version  Print version

What it exposes

~47 MCP tools mapped onto the core Forgeplan operations:

Artifact lifecycle — new, validate, review, activate, supersede, deprecate, stale, renew, reopen
Query + discovery — list, get, search, blocked, order, tree, discover, blindspots, gaps
Scoring + reasoning — score, fgr, reason, route, estimate
Evidence + links — link, unlink, new_evidence
Tags — tag, untag
Health + observability — health, status, coverage, drift
FPF knowledge base — fpf_search, fpf_section, fpf_check
Memory — remember, recall, promote

Forgeplan is MCP-first: the CLI is a convenience wrapper, and the full power of the tool is designed to be driven by AI agents through this server.

Transport

stdio only — no HTTP, no sockets, no network exposure. The MCP client owns the process and communicates over pipes.
One workspace per server — the server runs in the current working directory and operates on ./.forgeplan/. Launch it from the project root.
Stateless — no long-lived state between requests beyond what’s in LanceDB and markdown.

Examples

Example 1: Claude Code client config

See “Typical usage” below.

Example 2: Manual smoke test

See “Manual usage (debugging)” below.

Typical usage (automatic)

You usually don’t run serve manually. MCP clients launch it as a child process via their config file. For Claude Code, add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "forgeplan": {
      "command": "forgeplan",
      "args": ["serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

Cursor (~/.cursor/mcp.json) and Windsurf use the same schema. Restart the client; Forgeplan tools (mcp__forgeplan__*) become available to the agent.

Manual usage (debugging)

Run serve directly only when you need to:

Debug a new MCP tool — wire it up by hand, pipe JSON-RPC requests in, inspect the response.
Validate protocol compliance — run against mcp-inspector or similar.
Smoke-test after a release — make sure the binary starts and lists its tool schema.

# Manual smoke test
cd /path/to/project
forgeplan serve
# (server waits on stdin for JSON-RPC messages)
# Ctrl-C to exit

For interactive exploration the mcp-inspector tool is much more productive than hand-writing JSON-RPC.

Troubleshooting

“No workspace found” — the server was launched in a directory without .forgeplan/. Set cwd in your MCP client config to the project root.
Tools missing in client — restart the MCP client after editing its config; most clients only read mcp.json at startup.
LLM features fail — LLM-backed tools (reason, route) need a provider configured in .forgeplan/config.yaml. See the LLM guide.
Semantic tools no-op — embed feature flag must be compiled in for semantic search; otherwise those tools fall back to keyword search.