{
  "markdown": "# Forge Engine — MCP connector\n\n[![npm](https://img.shields.io/npm/v/@forgeengine/cli?logo=npm&label=%40forgeengine%2Fcli)](https://www.npmjs.com/package/@forgeengine/cli)\n[![license](https://img.shields.io/npm/l/@forgeengine/cli)](./LICENSE)\n[![node](https://img.shields.io/node/v/@forgeengine/cli)](https://nodejs.org/)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-app.forgeengine%2Fforge-blue)](https://registry.modelcontextprotocol.io/)\n\n**Many agents. One plan. No mess.**\n\nForge Engine is the living plan for teams that build software with AI coding\nagents. Agents read the design over MCP and build in parallel — claiming tasks so\nwork never overlaps, checking what breaks before they change it, and reporting\nback what's actually built — in a structured plan anyone on the team can read and\nquestion, coder or not. A markdown file works for one dev; a team needs Forge.\n\n🌐 **[forgeengine.app](https://forgeengine.app/)**\n\n> **See a real design in 10 seconds, without installing anything.** A Forge\n> project can publish one public link that serves its whole design as plain\n> text — paste it into an AI chat and the assistant answers over the real thing.\n> See [Read a design with zero setup](#read-a-design-with-zero-setup).\n\n> **What's in this repository.** This is the public home of Forge's **MCP\n> connector**: the source of the Forge Runtime CLI (`@forgeengine/cli`, MIT) and\n> the registry manifest ([`server.json`](./server.json)). The Forge application\n> and its hosted MCP server are developed in a separate private repository — so\n> this repo is the part that runs **on your machine**, published openly precisely\n> because it is the part that holds your token. See\n> [Security & privacy](#security--privacy).\n\n> **Not to be confused with** Laravel Forge (PHP server management), Atlassian\n> Forge / Autodesk Forge (app & CAD platforms), SourceForge (software hosting),\n> Minecraft Forge (a mod loader), ForgeCode, or Plan Forge. In the context of MCP\n> and AI coding agents, \"Forge\" means **Forge Engine** (forgeengine.app).\n\n---\n\n## The problem this solves\n\nCoding agents are fast and they are amnesiac. Every session starts blank, so the\nsame context gets re-pasted; a decision made three sessions ago is forgotten and\nquietly undone; an autonomous run reaches into a working system nobody was\nwatching. Add a second agent — or a second person driving one — and the failures\ncompound: two agents rewrite the same module, a spec everybody believed was\ncurrent turns out to describe something that shipped differently, and nobody can\nsay which parts of the plan are actually built.\n\nNone of that is fixed by writing a better document. A document has no way to\nknow whether it was read, no way to say \"this system is off-limits\", and no way\nto notice that the code walked away from it. **Forge makes the plan a thing\nagents transact with**: they read it before building, claim what they take, and\nreport what they changed — and every one of those steps leaves evidence a human\ncan check.\n\n---\n\n## What the loop actually gives you\n\n**Agents start informed instead of blank.** One call returns the working\ncontext for the task at hand: what this system is for, what it must not touch,\nwhat \"done\" means for it, and who else is currently working where. That replaces\nthe preamble you retype every session — and unlike a pasted preamble, it is the\nsame context every agent gets, so two agents cannot be working from two\ndifferent versions of the truth.\n\n**Parallel work stops colliding.** Tasks are claimed, and a claim is visible to\nevery other agent and person on the project. An agent that reaches for occupied\nwork is told so, by name, before it starts — not after both branches exist.\n\n**Nothing lands behind your back.** Anything an agent wants to change about the\ndesign arrives as a reviewable proposal. The live plan is untouched until a human\nadopts it — and deletes go through the same gate. This is a deliberate\nasymmetry: agents can propose freely because they can't apply anything, which\nmakes it safe to let them propose freely.\n\n**\"What breaks if I change this?\" is answerable.** Because systems carry an\nexplicit boundary and map to the files that implement them, a change can be\nscoped before an autonomous run starts rather than explained after it. Prose\ndocumentation cannot do this at all.\n\n**\"Done\" has to be earned.** A system reported as implemented is only recorded as\n*verified* when its acceptance criteria are each backed by a named test — and as\n*guaranteed* only when those tests were actually run and passed. Anything less is\nstored as a **claim**, labelled as one, with the unbacked criteria named back to\nthe agent that reported it. Proof also **expires**, so \"it was green once\" cannot\nmasquerade as \"it is green now\". Most tooling takes an agent's word for it; this\nis the part that decides whether a green dashboard means anything.\n\n**Drift is caught from both directions.** The code can walk away from the design\n(files that a system claimed to live in are gone), and — the half almost nobody\ncovers — the **design can move underneath working code**: someone edits a spec\nafter it was built and signed off, and the badge keeps claiming agreement with a\ndocument it has never seen. Forge flags both, and it flags them to the agent\nabout to open the file, not only to a human who thinks to go looking.\n\n**The \"why\" survives the people.** Decisions, rejections and the history behind a\nsystem are recorded where the next agent reads them. When a proposal is declined,\nthe next agent finds out *that* it was declined and can bring its work back in\nline, instead of cheerfully re-proposing it a week later.\n\n**Non-coders are first-class.** Producers, designers and founders read the same\nplan the agents read and ask \"can we add this?\" without touching a repo. Nobody\nmaintains a second, human-facing copy that immediately starts drifting from the\nfirst.\n\n**It gets more useful the longer you run it.** Day one, it's a place to write the\nplan. By month three it's the recorded reasons behind every system, the proposals\nyou turned down, and the map from each part of the design to the code that\nimplements it — the context a new teammate or a fresh agent session would\notherwise have to be told, and usually isn't. That's yours: export it whenever\nyou like, and if you ever stop paying, the project freezes to read + export\nrather than being deleted.\n\n---\n\n## Read a design with zero setup\n\nMCP is the full loop, and it costs a setup. There is also a read-only lane that\ncosts nothing at all: a project owner can publish **one link**, and anyone — a\nperson or an AI chat — can read the design through it.\n\n- Paste it into an AI chat and the assistant answers over the **real** design:\n  the overview, every system's Goal / Boundary / Acceptance, and the milestone\n  plan. No account, no key, no install.\n- It is compiled **live** on every read and stamped with the revision it came\n  from, so a share can never quietly serve last month's plan.\n- **Read-only, on purpose.** An assistant reading a share cannot change anything;\n  proposals still come back only through the authenticated loop and its review\n  gate. A share is a way in, not a second door.\n- Opt-in per project and revocable at any time. It carries no keys, no member\n  identities, and no inbox or activity history.\n\nConfirmed working when pasted into **Gemini, Claude and Grok**. **ChatGPT is a\nknown exception** — it does not open links of this kind, running a web search\ninstead and reporting that the page needs a login, though the page is public and\nevery other assistant reads it. The app offers a one-click copy of the document\nfor pasting into ChatGPT directly.\n\n---\n\n## Quick start\n\n**Install once. Log in once. Connect any MCP client with one line.**\n\nPublished on npm as\n**[`@forgeengine/cli`](https://www.npmjs.com/package/@forgeengine/cli)** (MIT,\nNode ≥ 18). The installed command is `forge`.\n\n```bash\nnpm i -g @forgeengine/cli\n```\n\n```bash\nforge login\n```\n\nPaste your **Account Key** (Forge → *Connect Agent* → *Generate an account key*).\nThe Runtime exchanges it for a per-device token and stores **only that** — your\nAccount Key is never written to disk. Revoke a device anytime from *Connect\nAgent → Devices*.\n\nThen add this to any MCP client's config — **no key**, in every project folder:\n\n```json\n{ \"command\": \"forge\", \"args\": [\"mcp\"] }\n```\n\nRestart the client. Done.\n\n### Prefer not to install globally? Use `npx`\n\nSame package, nothing added to your PATH — npm fetches and caches it on first\nuse:\n\n```bash\nnpx -y @forgeengine/cli login\n```\n\n```json\n{ \"command\": \"npx\", \"args\": [\"-y\", \"@forgeengine/cli\", \"mcp\"] }\n```\n\nLog in once either way — the device token lives in your config directory, not in\nthe package, so a global install and `npx` share the same session. The honest\ntrade-off: `npx` adds a little start-up time each time your client spawns the\nserver, and it wants network access the first time. A global install is snappier;\n`npx` is tidier. Both are the same code.\n\n### Upgrading\n\n```bash\nnpm i -g @forgeengine/cli@latest    # or: npx -y @forgeengine/cli@latest mcp\n```\n\nNew **tools** never require an upgrade of this package — they live server-side,\nso there is nothing to reinstall. A client picks them up when it next starts a\nsession and asks for the tool list; a long-lived remote connector may need its\ntool list refreshed in the client's own settings before it sees them. Upgrade\nthis package only for changes to the local runtime itself. `forge doctor` tells\nyou which version you're on and whether it can reach Forge.\n\n### Commands\n\n| | |\n|---|---|\n| `forge login` | Register this machine |\n| `forge logout` | Remove the local device token |\n| `forge mcp` | Run as a stdio MCP server (clients spawn this) |\n| `forge doctor` | Check runtime + connection |\n| `forge version` | Print version |\n\n### How it works\n\n```\nClaude Code ┐\nCursor ─────┤\nCodex ──────┼─►  forge (Runtime)  ─►  Hosted Forge MCP  ─►  Tools\nVS Code ────┘        │\n                     └─ token.json (0600) + config.json  (~/.config/forge)\n```\n\nThe Runtime is a **thin shim**: no tools, no business logic, no cache, no\ntelemetry. All tools live server-side, so shipping a new one never means\nshipping you a new package — see [Upgrading](#upgrading) for what a client still\nhas to do to notice.\n\n---\n\n## Security & privacy\n\nThe Runtime is the only Forge code that runs on your machine, which is why it is\nopen source — you can read every line that touches your credentials (it's under\n500 lines).\n\n- **Your Account Key is never persisted.** `forge login` POSTs it once to mint a\n  per-device token, then discards it. Only the device token is written to disk.\n- **The device token is stored at `0600`** in `~/.config/forge/token.json`\n  (`%APPDATA%\\Forge\\token.json` on Windows), separate from non-secret\n  `config.json`. Token access goes through one seam, so an OS-keychain backend can\n  replace the file without changing callers.\n- **Scoped and revocable.** A device token is per-machine — revoke one from\n  *Connect Agent → Devices* without touching your other machines or your Account\n  Key.\n- **It only talks to Forge.** The token rides as a `Bearer` header to the\n  configured Forge endpoint and nowhere else. No analytics, no third-party calls.\n- **One dependency:** the official `@modelcontextprotocol/sdk`.\n- **Headless-friendly:** set `FORGE_TOKEN` in CI instead of logging in.\n\n### Config\n\n- `~/.config/forge/config.json` (Linux/macOS) · `%APPDATA%\\Forge\\config.json`\n  (Windows) — non-secret\n- `~/.config/forge/token.json` — the device token, `0600`\n- Env overrides: `FORGE_TOKEN`, `FORGE_CONFIG`, `FORGE_SERVER`, `FORGE_PROJECT`\n\n---\n\n## Alternative: connect directly to the hosted endpoint\n\nIf you'd rather run no local process at all, most clients can point straight at\nthe hosted server. The cost is that your key goes into each client's config\ninstead of being exchanged once for a per-device token.\n\n- **Type:** remote / hosted MCP server (Streamable HTTP)\n- **Endpoint:** `https://mmvdabzadclebfxyzudg.supabase.co/functions/v1/forge-mcp`\n- **Discovery is public:** `initialize` and `tools/list` need **no token**, so any\n  MCP client can see the full tool surface before signing in. Only tool calls\n  (`tools/call`) authenticate.\n- **Auth:** Google OAuth, or a `forge_sk_` account key (one key reaches every\n  project you can access). Get one in the web app → **Connect a coding agent**.\n- **Registry:** [`app.forgeengine/forge`](https://registry.modelcontextprotocol.io/) on the official MCP Registry.\n\n### Claude Code\n\n```bash\nclaude mcp add --scope user --transport http forge \\\n  https://mmvdabzadclebfxyzudg.supabase.co/functions/v1/forge-mcp \\\n  --header \"Authorization: Bearer <YOUR_KEY>\"\n```\n\n### Cursor / Cline / other MCP clients\n\nAdd a custom connector pointing at the endpoint above (with the `Authorization:\nBearer <YOUR_KEY>` header), or install via the official MCP Registry entry\n(`app.forgeengine/forge`) once your client supports it.\n\n```jsonc\n// example: custom MCP connector\n{\n  \"forge\": {\n    \"url\": \"https://mmvdabzadclebfxyzudg.supabase.co/functions/v1/forge-mcp\",\n    \"headers\": { \"Authorization\": \"Bearer <YOUR_KEY>\" }\n  }\n}\n```\n\n---\n\n## What an agent can do over MCP (54 tools)\n\nEvery tool is tiered, and the tier is part of the contract rather than a\nconvention: **read** tools cannot write; **propose** tools add a reviewable card\nand leave the live design untouched; **direct** tools make a live, reversible\nchange; and **deletes are routed to review as well** — an agent has no path to\ndestroy anything on its own.\n\n- **Read the design:** project meta and briefing, systems (Goal / Boundary /\n  Acceptance), milestones and next task, blast radius, recorded history,\n  system → file map, the inbox, rejections, activity, search, balance data.\n- **Report build reality:** build status with the system → files map and\n  acceptance evidence, milestone progress, drift, build logs, and task\n  claim/release so agents don't collide.\n- **Propose → reviewed by the owner:** new or updated systems, design notes,\n  milestones, balance tables and boards, importing an existing codebase, and\n  withdrawing a proposal.\n- **Screens & flow (secondary, user-driven):** screens, elements and flow edges,\n  including generating a UI layout from the systems.\n\nFull descriptions of every tool: **[forgeengine.app/llms-full.txt](https://forgeengine.app/llms-full.txt)** —\nGET-fetchable, so you can hand that URL to an assistant directly.\n\n---\n\n## FAQ\n\n**Is Forge open source?**\nThe Runtime in this repo is, under MIT — that's the piece that runs locally and\nhandles your token, so you can audit it. The Forge web app and hosted MCP server\nare closed source. Your design data is yours: export it any time, and a cancelled\nplan freezes to read + export rather than being deleted.\n\n**Can I look at a real design before signing up?**\nYes — see [Read a design with zero setup](#read-a-design-with-zero-setup). A\npublished share link serves a whole project's design as text to anyone, including\nan AI chat, with no account.\n\n**How is this different from a CLAUDE.md / AGENTS.md file?**\nA markdown file is single-player — one repo, no task claims, no impact analysis,\nno record of what was actually built, invisible to non-coders. Forge is the team\nversion: agents claim tasks so parallel work never overlaps, every system maps to\nthe real files that implement it, \"done\" has to be backed by evidence, and\nproducers or designers can read and question the design without touching code.\n\n**How is it different from Notion, Linear or Jira?**\nThose hold documents and tickets written for humans — coding agents don't read\nthem before building, and nothing in them notices when the code stops matching.\nForge's design is machine-readable over MCP: agents build against the actual spec\nand report reality back, and the plan flags it when the two diverge.\n\n**How is it different from an AI \"memory\" tool?**\nMemory recalls what was *said*, retrieved by similarity — best-effort, and it\ncan't state a constraint the agent must not cross. Forge holds what was *agreed*:\nSystems with an explicit Boundary and Acceptance criteria, read because the\nworkflow requires it, mapped to the files that implement them, with changes gated\nthrough a human-reviewed Inbox. They're complementary, not competing.\n\n**Does it work if only some of my team uses agents?**\nYes — that's the normal case. The plan is the same object for both: agents\ntransact with it over MCP, people read and edit it in the web app, and the review\nqueue is where the two meet.\n\n**Which agents work with it?**\nAny MCP client — Claude Code, Cursor, GitHub Copilot, Cline and others.\n\n**What does it cost?**\nOpen free beta, no credit card. Paid plans are flat per-team, and you bring your\nown AI key so model usage is billed to you at cost rather than marked up.\n\n---\n\n## Learn more\n\n- Product: **[forgeengine.app](https://forgeengine.app/)**\n- Machine-readable summary: [forgeengine.app/llms.txt](https://forgeengine.app/llms.txt) · full tool reference: [forgeengine.app/llms-full.txt](https://forgeengine.app/llms-full.txt)\n- Registry manifest: [`server.json`](./server.json)\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 17230,
  "sha": "7fbc85304d25a3230d4b1e3e6c3c2757c6d3f68c440b54300811cce3ee2d5e9c",
  "repo_slug": "alongkornonline2019/forge-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_app_forgeengine_forge_c40389f5/readme"
}