Forge Engine

Forge Engine — MCP connector

Many agents. One plan. No mess.

Forge Engine is the living plan for teams that build software with AI coding agents. Agents read the design over MCP and build in parallel — claiming tasks so work never overlaps, checking what breaks before they change it, and reporting back what's actually built — in a structured plan anyone on the team can read and question, coder or not. A markdown file works for one dev; a team needs Forge.

🌐 [forgeengine.app](https://forgeengine.app/)

See a real design in 10 seconds, without installing anything. A Forge

project can publish one public link that serves its whole design as plain

text — paste it into an AI chat and the assistant answers over the real thing.

See Read a design with zero setup.

What's in this repository. This is the public home of Forge's **MCP

connector**: the source of the Forge Runtime CLI (@forgeengine/cli, MIT) and

the registry manifest (server.json). The Forge application

and its hosted MCP server are developed in a separate private repository — so

this repo is the part that runs on your machine, published openly precisely

because it is the part that holds your token. See

Security & privacy.

Not to be confused with Laravel Forge (PHP server management), Atlassian

Forge / Autodesk Forge (app & CAD platforms), SourceForge (software hosting),

Minecraft Forge (a mod loader), ForgeCode, or Plan Forge. In the context of MCP

and AI coding agents, "Forge" means Forge Engine (forgeengine.app).

---

The problem this solves

Coding agents are fast and they are amnesiac. Every session starts blank, so the same context gets re-pasted; a decision made three sessions ago is forgotten and quietly undone; an autonomous run reaches into a working system nobody was watching. Add a second agent — or a second person driving one — and the failures compound: two agents rewrite the same module, a spec everybody believed was current turns out to describe something that shipped differently, and nobody can say which parts of the plan are actually built.

None of that is fixed by writing a better document. A document has no way to know whether it was read, no way to say "this system is off-limits", and no way to notice that the code walked away from it. Forge makes the plan a thing agents transact with: they read it before building, claim what they take, and report what they changed — and every one of those steps leaves evidence a human can check.

---

What the loop actually gives you

Agents start informed instead of blank. One call returns the working context for the task at hand: what this system is for, what it must not touch, what "done" means for it, and who else is currently working where. That replaces the preamble you retype every session — and unlike a pasted preamble, it is the same context every agent gets, so two agents cannot be working from two different versions of the truth.

Parallel work stops colliding. Tasks are claimed, and a claim is visible to every other agent and person on the project. An agent that reaches for occupied work is told so, by name, before it starts — not after both branches exist.

Nothing lands behind your back. Anything an agent wants to change about the design arrives as a reviewable proposal. The live plan is untouched until a human adopts it — and deletes go through the same gate. This is a deliberate asymmetry: agents can propose freely because they can't apply anything, which makes it safe to let them propose freely.

"What breaks if I change this?" is answerable. Because systems carry an explicit boundary and map to the files that implement them, a change can be scoped before an autonomous run starts rather than explained after it. Prose documentation cannot do this at all.

"Done" has to be earned. A system reported as implemented is only recorded as *verified* when its acceptance criteria are each backed by a named test — and as *guaranteed* only when those tests were actually run and passed. Anything less is stored as a claim, labelled as one, with the unbacked criteria named back to the agent that reported it. Proof also expires, so "it was green once" cannot masquerade as "it is green now". Most tooling takes an agent's word for it; this is the part that decides whether a green dashboard means anything.

Drift is caught from both directions. The code can walk away from the design (files that a system claimed to live in are gone), and — the half almost nobody covers — the design can move underneath working code: someone edits a spec after it was built and signed off, and the badge keeps claiming agreement with a document it has never seen. Forge flags both, and it flags them to the agent about to open the file, not only to a human who thinks to go looking.

The "why" survives the people. Decisions, rejections and the history behind a system are recorded where the next agent reads them. When a proposal is declined, the next agent finds out *that* it was declined and can bring its work back in line, instead of cheerfully re-proposing it a week later.

Non-coders are first-class. Producers, designers and founders read the same plan the agents read and ask "can we add this?" without touching a repo. Nobody maintains a second, human-facing copy that immediately starts drifting from the first.

It gets more useful the longer you run it. Day one, it's a place to write the plan. By month three it's the recorded reasons behind every system, the proposals you turned down, and the map from each part of the design to the code that implements it — the context a new teammate or a fresh agent session would otherwise have to be told, and usually isn't. That's yours: export it whenever you like, and if you ever stop paying, the project freezes to read + export rather than being deleted.

---

Read a design with zero setup

MCP is the full loop, and it costs a setup. There is also a read-only lane that costs nothing at all: a project owner can publish one link, and anyone — a person or an AI chat — can read the design through it.

• Paste it into an AI chat and the assistant answers over the real design: the overview, every system's Goal / Boundary / Acceptance, and the milestone plan. No account, no key, no install.
• It is compiled live on every read and stamped with the revision it came from, so a share can never quietly serve last month's plan.
• Read-only, on purpose. An assistant reading a share cannot change anything; proposals still come back only through the authenticated loop and its review gate. A share is a way in, not a second door.
• Opt-in per project and revocable at any time. It carries no keys, no member identities, and no inbox or activity history.

Confirmed working when pasted into Gemini, Claude and Grok. ChatGPT is a known exception — it does not open links of this kind, running a web search instead and reporting that the page needs a login, though the page is public and every other assistant reads it. The app offers a one-click copy of the document for pasting into ChatGPT directly.

---

Quick start

Install once. Log in once. Connect any MCP client with one line.

Published on npm as [`@forgeengine/cli`](https://www.npmjs.com/package/@forgeengine/cli) (MIT, Node ≥ 18). The installed command is forge.

npm i -g @forgeengine/cli

forge login

Paste your Account Key (Forge → *Connect Agent* → *Generate an account key*). The Runtime exchanges it for a per-device token and stores only that — your Account Key is never written to disk. Revoke a device anytime from *Connect Agent → Devices*.

Then add this to any MCP client's config — no key, in every project folder:

{ "command": "forge", "args": ["mcp"] }

Restart the client. Done.

Prefer not to install globally? Use npx

Same package, nothing added to your PATH — npm fetches and caches it on first use:

npx -y @forgeengine/cli login

{ "command": "npx", "args": ["-y", "@forgeengine/cli", "mcp"] }

Log in once either way — the device token lives in your config directory, not in the package, so a global install and npx share the same session. The honest trade-off: npx adds a little start-up time each time your client spawns the server, and it wants network access the first time. A global install is snappier; npx is tidier. Both are the same code.

Upgrading

npm i -g @forgeengine/cli@latest    # or: npx -y @forgeengine/cli@latest mcp

New tools never require an upgrade of this package — they live server-side, so there is nothing to reinstall. A client picks them up when it next starts a session and asks for the tool list; a long-lived remote connector may need its tool list refreshed in the client's own settings before it sees them. Upgrade this package only for changes to the local runtime itself. forge doctor tells you which version you're on and whether it can reach Forge.

Commands

How it works

Claude Code ┐

Cursor ─────┤ Codex ──────┼─► forge (Runtime) ─► Hosted Forge MCP ─► Tools VS Code ────┘ │ └─ token.json (0600) + config.json (~/.config/forge)

The Runtime is a thin shim: no tools, no business logic, no cache, no telemetry. All tools live server-side, so shipping a new one never means shipping you a new package — see Upgrading for what a client still has to do to notice.

---

Security & privacy

The Runtime is the only Forge code that runs on your machine, which is why it is open source — you can read every line that touches your credentials (it's under 500 lines).

• Your Account Key is never persisted. forge login POSTs it once to mint a per-device token, then discards it. Only the device token is written to disk.
• The device token is stored at `0600` in ~/.config/forge/token.json (%APPDATA%\Forge\token.json on Windows), separate from non-secret config.json. Token access goes through one seam, so an OS-keychain backend can replace the file without changing callers.
• Scoped and revocable. A device token is per-machine — revoke one from *Connect Agent → Devices* without touching your other machines or your Account Key.
• It only talks to Forge. The token rides as a Bearer header to the configured Forge endpoint and nowhere else. No analytics, no third-party calls.
• One dependency: the official @modelcontextprotocol/sdk.
• Headless-friendly: set FORGE_TOKEN in CI instead of logging in.

Config

• ~/.config/forge/config.json (Linux/macOS) · %APPDATA%\Forge\config.json (Windows) — non-secret
• ~/.config/forge/token.json — the device token, 0600
• Env overrides: FORGE_TOKEN, FORGE_CONFIG, FORGE_SERVER, FORGE_PROJECT

---

Alternative: connect directly to the hosted endpoint

If you'd rather run no local process at all, most clients can point straight at the hosted server. The cost is that your key goes into each client's config instead of being exchanged once for a per-device token.

• Type: remote / hosted MCP server (Stream