Onceworlds
Log inSign up
CLI & MCP

CLI & MCP

One package, @onceworlds/cli: commands for a terminal, and the same as MCP tools for your AI tool.

Set it up

1. Log in

npx @onceworlds/cli login

2. Add it to Claude Code

claude mcp add --scope user onceworlds -- npx -y @onceworlds/cli mcp

3. Ask it to make a game. Each draft shows up on Create.

1. Log in

npx @onceworlds/cli login

2. Add it to Codex

codex mcp add onceworlds -- npx -y @onceworlds/cli mcp

3. Ask it to make a game. Each draft shows up on Create.

1. Log in

npx @onceworlds/cli login

2. Add this to your tool's MCP settings (Cursor, Windsurf, Gemini CLI, Claude Desktop and more)

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

VS Code calls the key servers. A tool without MCP can run npx @onceworlds/cli deploy and npx @onceworlds/cli playtest in a terminal instead.

3. Ask it to make a game. Each draft shows up on Create.

How the MCP works

MCP is how an AI tool learns new abilities. Everything runs on your computer: Onceworlds never calls a model, so it uses your own AI account. It works with Claude Code and Codex, and with other tools that run MCP servers, such as Cursor, Windsurf, Gemini CLI, Claude Desktop and VS Code. A tool without MCP can run the same commands in a terminal.

  1. Ask for a game

    It reads the guide, starts a folder and builds the game in it.

  2. Play each draft

    After every change it pushes a draft. It shows up on Create, playable with the menu and multiplayer.

  3. Send back what's wrong

    Errors you hit go back to your AI, or copy a note about what should change from the draft's page.

  4. Publish

    You click Publish and choose who can play.

The connection can only push drafts of your own games, never publish, and you can disconnect it on Create. Your project folder is the source: keep your own backup (or put it on GitHub). A scene project (project.json) also opens in Build.

MCP tools

read_guideReads the platform guide, the engine guide or the API reference, by topic or heading.
new_gameStarts a folder from a kit or a template.
list_kitsThe kits a game starts from: a complete engine game for each kind.
api_lookupThe engine’s API in a few lines: a signature, what it does, an example.
recipeShort, tested code for a kind of game or a feature.
search_assetsModels, sprites, materials and sounds from the engine’s library.
checkLooks through the files for common mistakes, and runs an engine game’s tests and simulated matches.
screenshotA picture of the game a few seconds into a match, or a poster.
deploy_previewPushes a draft for you to play.
playtestPlays the draft as several guests in a browser on your computer and reports what broke.
game_statusThe errors your plays of the newest draft hit.
list_gamesYour games.

Commands

Run them with npx @onceworlds/cli <command>.

loginConnects this computer to your account (you approve a code in the browser).
mcpRuns as an MCP server for your AI tool.
new [dir] --kit <kit>Starts a game from a kit (--list shows them), or --template <name> from a Build template.
dev [dir]Deploys to a local platform, then again on every change.
check [dir]Before a deploy: common mistakes, and an engine game’s tests and simulated matches.
shot [dir]A picture of the game to look at.
posters [dir]Draws an engine game’s store art.
doctor [dir]Looks for what games often ship with (--fix writes How to play).
deploy [dir]Uploads the game: from GitHub Actions it goes live; from your computer it’s a draft.
playtest [dir]Plays your latest draft in a headless browser as several guests.
init [dir]Sets a folder up for Onceworlds: onceworlds.json, the GitHub workflow, AGENTS.md.
api <name>Looks the engine’s API up.
recipe [name]Short, tested code for common games and features.
guide [topic]Reads a topic of the engine guide.