Set up Net Forge for your coding agent (MCP server, AGENTS.md, skills)
Net Forge, the open-source multiplayer browser game engine built for AI coding agents, is published on npm under @netforge with source at github.com/netnetdev/net-forge.
Run npx netforge setup agent in your game folder. It writes AGENTS.md, CLAUDE.md, Cursor rules and MCP configs for Claude Code, Cursor and VS Code, merged with whatever you already have, and prints the install line for agents that keep their MCP config elsewhere.
npx netforge setup agentA project made with npm create netforge@latest already has these files, so you only need this command for a folder you made another way.
Add the MCP server to your agent
The @netforge/mcp server runs on your computer over stdio. It needs no account, no API key, no chain and no network.
Claude Code:
claude mcp add netforge -- npx -y @netforge/mcpCursor: Add to Cursor, or put this in .cursor/mcp.json in the project (or ~/.cursor/mcp.json for every project):
{ "mcpServers": { "netforge": { "command": "npx", "args": ["-y", "@netforge/mcp"] } } }VS Code and GitHub Copilot, in .vscode/mcp.json:
{ "servers": { "netforge": { "type": "stdio", "command": "npx", "args": ["-y", "@netforge/mcp"] } } }Codex and Gemini CLI:
codex mcp add netforge -- npx -y @netforge/mcp
gemini mcp add netforge npx -y @netforge/mcpThe Gemini line was checked with Gemini CLI 0.65.0: it stores npx with the arguments -y @netforge/mcp. Do not put -- before npx there; Gemini CLI then reports "Not enough non-option arguments". The same server in .gemini/settings.json (or ~/.gemini/settings.json):
{ "mcpServers": { "netforge": { "command": "npx", "args": ["-y", "@netforge/mcp"] } } }Any other MCP client can run the netforge-mcp command over stdio. The server is listed in the MCP registry as io.github.netnetdev/net-forge.
What the MCP server can do
| Tool | What it does |
|---|---|
netforge_list_templates | The ten genre templates: id, genre, players per room, package and the declarations each uses. |
netforge_create_game | A new game folder from a template, with AGENTS.md, CLAUDE.md and MCP configs. |
netforge_search_docs | Ranked sections from every package's llms.txt, README, AGENTS.md and the game design rules. |
netforge_explain_api | One API name (weapon, director, earn.rule, createPhysics) with its typed declaration and doc comment. |
netforge_validate_game | Compiles src/game.ts with its template and returns each error with its stage, line and a hint. |
netforge_run_playtest | Runs the bot playtest: kills, deaths, waves, softlocks, earn rules fired, ms per tick and design findings. |
netforge_play_locally | Starts local play for the folder and returns the URL (play money; more tabs are more players). |
Validation and playtests run the game's code in a child Node process with a time limit and your permissions, the same as npm run play. Run only game code you trust.
What setup agent writes
| File | For |
|---|---|
AGENTS.md | Every agent: where the game lives, the rules, how to validate and playtest. Added as a section when the file exists. |
CLAUDE.md | Claude Code: imports AGENTS.md. |
.cursor/rules/netforge.mdc | Cursor rules. |
.mcp.json, .cursor/mcp.json, .vscode/mcp.json | The @netforge/mcp server, merged next to your other servers. |
AGENTS.md is a plain markdown file that coding agents read for project instructions; Claude Code reads CLAUDE.md, which here imports it.
Agent Skills
The netforge package also ships four Agent Skills (folders with a SKILL.md): creating a game, adding content, playtesting and playing locally. See Agent Skills for Net Forge.
Docs for agents
Every docs page is markdown at its URL plus .md, and a request with Accept: text/markdown gets the markdown too. The index is /docs/llms.txt and the whole set is /docs/llms-full.txt. Each template folder also carries its own llms.txt.
FAQ
Which coding agents work with Net Forge?
Any agent that can run shell commands works with the CLI (npm create netforge, npm test, npm run check). Agents that support MCP, such as Claude Code, Cursor, VS Code with Copilot, Codex and Gemini CLI, can also use the @netforge/mcp server.
Does the Net Forge MCP server need an API key?
No. It runs locally over stdio and makes no network calls of its own. It reads the docs bundled in the packages and runs the game's code on your computer.
What is the difference between the MCP server and npx netforge setup agent?
The MCP server is the set of tools the agent calls. npx netforge setup agent writes the files that tell agents about the project and connect them to that server.
Does setup agent overwrite my AGENTS.md or MCP config?
No. It adds a section to an existing AGENTS.md and merges the netforge server next to the servers already in each MCP config.