# Set up Net Forge for your coding agent (MCP server, AGENTS.md, skills)

> Run npx netforge setup agent in a game folder to write AGENTS.md, CLAUDE.md, Cursor rules and MCP configs, or add the @netforge/mcp server to Claude Code, Cursor, VS Code, Codex or Gemini CLI with one line. The server lists templates, scaffolds games, searches the docs, validates game modules and runs bot playtests, with no keys and no network.

Net Forge, the open-source multiplayer browser game engine built for AI coding agents, is published on npm under `@netforge` with source at https://github.com/netnetdev/net-forge.

Source: https://forge.netnet.capital/docs/agents  
Last updated: 2026-10-23. Checked against @netforge/engine 0.2.0.

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.

```sh
npx netforge setup agent
```

A 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:

```sh
claude mcp add netforge -- npx -y @netforge/mcp
```

Cursor: [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=netforge&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBuZXRmb3JnZS9tY3AiXX0=), or put this in `.cursor/mcp.json` in the project (or `~/.cursor/mcp.json` for every project):

```json
{ "mcpServers": { "netforge": { "command": "npx", "args": ["-y", "@netforge/mcp"] } } }
```

VS Code and GitHub Copilot, in `.vscode/mcp.json`:

```json
{ "servers": { "netforge": { "type": "stdio", "command": "npx", "args": ["-y", "@netforge/mcp"] } } }
```

Codex and Gemini CLI:

```sh
codex mcp add netforge -- npx -y @netforge/mcp
gemini mcp add netforge npx -y @netforge/mcp
```

The 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`):

```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](https://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](https://forge.netnet.capital/docs/skills.md).

## 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](https://forge.netnet.capital/docs/llms.txt.md) and the whole set is [/docs/llms-full.txt](https://forge.netnet.capital/docs/llms-full.txt.md). 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.