MCP Server — Quick Start

Start the server, verify it's running, and call your first forge tools in under five minutes.

Starting the Server

# Install dependencies (first time only)
cd pforge-mcp && npm install && cd ..

# Full server: MCP + HTTP + WebSocket
node pforge-mcp/server.mjs

# Dashboard only (no MCP stdio)
node pforge-mcp/server.mjs --dashboard-only

# Custom project path
node pforge-mcp/server.mjs --project /path/to/project

With .vscode/mcp.json configured (created by setup.ps1 / setup.sh), the server auto-starts when Copilot calls any forge tool, you don't need to start it manually.

Verify It's Running

# Check the health endpoint
curl http://localhost:3100/api/status

# Or open the dashboard in your browser
open http://localhost:3100

Essential Tools

These are the tools you'll use most often. Start with forge_capabilities to discover the full surface; use forge_run_plan to execute your work.

forge_capabilities — Discovery

Returns the complete, always-authoritative API surface. Call this first.

forge_capabilities({})

Returns: tool schemas, intents, config keys, available extensions, per-tool error codes.

forge_smith — Environment Check

Diagnose your setup: VS Code config, Node version, MCP connectivity, preset health, version currency. Run this when something isn't working.

forge_smith({})

forge_run_plan — Execute a Plan

Execute a hardened plan file. Spawns workers, validates gates after each slice, tracks tokens and cost. This is the core execution command.

// Estimate cost before running (recommended)
forge_run_plan({ plan: "docs/plans/Phase-1.md", estimate: true })

// Execute
forge_run_plan({ plan: "docs/plans/Phase-1.md" })

// Execute with quorum mode
forge_run_plan({ plan: "docs/plans/Phase-1.md", quorum: "auto" })

// Resume from a specific slice
forge_run_plan({ plan: "docs/plans/Phase-1.md", resumeFrom: 3 })

Quorum modes: auto (adaptive), power (flagship models, threshold 5), speed (fast models, threshold 7), false (single model, no quorum).

forge_plan_status — Execution Status

Poll the status of the currently running (or most recent) plan execution. Returns per-slice results, tokens consumed, duration, and gate outcomes.

forge_plan_status({})

forge_abort — Stop Execution

Abort the currently running plan execution. The orchestrator finishes the current slice's work-in-progress before stopping.

forge_abort({})

forge_diagnose — Bug Investigation

Multi-model bug investigation: provide a source file (and optionally models) and receive root-cause analysis plus fix recommendations.

forge_diagnose({ file: "src/services/billing.ts" })

forge_analyze — Consistency Scoring

Cross-artifact consistency scoring (0–100 across 4 dimensions). Checks that your plans, code, tests, and docs are in sync. Run before shipping. plan is required and can point at a plan markdown or a source file.

forge_analyze({ plan: "docs/plans/Phase-1-AUTH-PLAN.md" })

forge_estimate_quorum — Cost Preview

Project the cost of a plan under all four quorum modes before executing. Always call this instead of hand-computing costs.

forge_estimate_quorum({ planPath: "docs/plans/Phase-1.md" })

Typical Workflow

1. 1. Discover, forge_capabilities({}) to see the live API surface
2. 2. Check setup, forge_smith({}) to confirm everything is green
3. 3. Estimate, forge_estimate_quorum({ planPath: "…" }) before any execution
4. 4. Run, forge_run_plan({ plan: "…" }) to execute your plan
5. 5. Monitor, forge_plan_status({}) to track progress
6. 6. Review, forge_analyze({ plan: "…" }) to confirm artifact consistency

📄 Full reference: capabilities, EVENTS.md on GitHub, tools.json on GitHub