portals-mcp

Prompt → playable 3D multiplayer game in the browser.

portals-mcp is an MCP server that turns Claude, Cursor, and any MCP-capable AI assistant into a game developer on Portals. Describe the game you want; the assistant builds the scene, wires the game logic, generates 3D models, textures, music, and sound effects, and hands you a link anyone can play instantly — multiplayer, in the browser, no engine or build step.

Quick Start

Run it directly:

npx -y portals-mcp@latest

Claude Code

claude mcp add portals -- npx -y portals-mcp@latest

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "portals": {
      "command": "npx",
      "args": ["-y", "portals-mcp@latest"]
    }
  }
}

Cursor

Use the button above, or add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "portals": {
      "command": "npx",
      "args": ["-y", "portals-mcp@latest"]
    }
  }
}

Codex

Add to ~/.codex/config.toml. For noninteractive tool calls (agent-driven sessions), set default_tools_approval_mode = "approve" — without it every tool call waits on a manual approval prompt.

[mcp_servers.portals]
command = "npx"
args = ["-y", "portals-mcp@latest"]
default_tools_approval_mode = "approve"

Environment variables

All optional — with no configuration the server opens a browser sign-in on first use.

| Variable | Required | Description | |----------|----------|-------------| | PORTALS_ACCESS_KEY | No | Portals access key. Set it (e.g. in a .env file next to your project) to skip the browser sign-in prompt. | | PORTALS_ROOM_ID | No | Default room ID used when a tool call doesn't specify one. | | PORTALS_DISABLE_TELEMETRY | No | Set to 1 to disable anonymous usage telemetry. | | PORTALS_MCP_TOOL_PROFILE | No | Tool-surface profile: compatibility (default, 53 v1 tools), expert (27 low-level authoring/debug tools), or local MCP 2.0 candidate builder (7 outcome tools). The candidate is opt-in until the benchmark promotion gates pass. |

First session

1. Call get_server_info first — it reports the server version, commit, and active tool profile. Record those values in any test report or bug filing so results are attributable to an exact build.
2. Ask your assistant to build something: "Create a mini golf course with a scoreboard." It will call authenticate (browser sign-in) the first time.
3. Behind the scenes the assistant calls get_context for targeted specs, gotchas, and recipes, and resolve_gameplay_capability / plan_gameplay_mechanic before making platform claims.
4. Edits land via apply_operations (scoped) or set_room_data (full snapshot); render_scene screenshots let it check its own work.

For local MCP 2.0 candidate testing, set PORTALS_MCP_TOOL_PROFILE=builder. The assistant sees only authenticate, manage_project, inspect_game, start_build, apply_build, playtest_build, and finalize_build. The connected assistant authors the plan, operations, Core test compilation, visual review, and repair intent itself. Portals supplies isolated workspaces, strict validation, Core probes, captures, evidence, rollback, and exact promotion. This profile has no path to the separate in-game prompt-to-build model executor. The 53-tool compatibility profile remains the default.

Install RC.2 for candidate testing with portals-mcp@next, not @latest. The RC.2 builder launch scope is deliberately narrower than the compatibility profile: it builds with the source room's existing contents and the operation types available in the isolated workspace. Marketplace discovery/acquisition and paid asset generation are not exposed by the seven builder tools, and the builder must not imply otherwise. They remain available only through the compatibility profile until the builder has discoverable asset intents, authenticated credit preflight, and promotion evidence.

Tools

The stable compatibility profile exposes 53 tools across authentication, marketplace assets, room building, scene design, live-game control, and AI asset generation. The opt-in MCP 2.0 candidate exposes 7 outcome tools; the expert profile exposes 27 low-level escape hatches. The machine-checked disposition and overlap map is available at docs://ai/tool-capability-manifest. Route checkpoint planning is an internal playtest capability, not a standalone public tool.

Authentication & Discovery

| Tool | Description | |------|-------------| | authenticate | Authenticate with Portals access key or browser flow | | get_help | Setup/workflow guidance with matching docs resources | | get_context | Returns targeted specs, syntax references, gotchas, recipes, and suggested tools | | lookup | Fast knowledge lookup for items, triggers, effects, systems, recipes | | resolve_gameplay_capability | Classify gameplay requests as supported directly, workaround, unsupported, or unknown | | plan_gameplay_mechanic | Return a compact implementation contract with required capabilities, objects, variables, triggers, validation, risks, and sources | | search_recipes | Search recipe manifest by keywords, tags, and patterns |

Marketplace & Inventory

| Tool | Description | |------|-------------| | search_marketplace | Search the Portals creator marketplace for assets (3D models, sounds, packs) | | get_pack_items | List the items contained in a marketplace pack | | list_marketplace_facets | List marketplace catalogue facets (categories, themes, visual styles, biomes, types) | | get_user_inventory | List assets the signed-in user has claimed or purchased | | claim_marketplace_item | Claim a free marketplace item into the user's inventory | | place_marketplace_items | Claim a batch of marketplace items and compose the ops to place them in the room | | get_room_build_items | List every item available in the room's in-game build palette | | add_to_room_inventory | Add marketplace items or packs to a room's build inventory | | wire_locked_door | Compose the ops to wire a locked-door mechanic between a key item and a door item |

Room Management

| Tool | Description | |------|-------------| | create_room | Create from 18 templates (art-gallery, blank, spaceship, etc.) | | duplicate_room | Clone a room with all data | | get_room_data | Download room snapshot to temp JSON with a SHA-256 freshness precondition | | inspect_room_data | Summarize room-data counts, item types, variables, triggers/actions, and warnings without dumping full JSON | | simulate_key_input | Audit and simulate OnKeyPressedEvent / OnKeyReleasedEvent mappings against a snapshot | | simulate_trigger_zone_input | Audit and simulate Trigger pressBtn / keyCode press-inside-zone behavior | | query_room | Query room data for specific items, logic, or structure | | update_room_settings | Modify name, description, image, privacy, loading screens | | set_room_settings | Update only scene settings (lighting, skybox, fog, movement, avatars, voice chat) |

Building

| Tool | Description | |------|-------------| | set_room_data | Replace entire room data only when its baseline snapshot is still current | | apply_operations | Atomic targeted ops against a mandatory fresh room download; never uploads partial batches or falls back to stale local data |

Assets

| Tool | Description | |------|-------------| | upload_glb | Upload one .glb file or all .glb files in a folder | | upload_image | Upload one image file or all supported image files in a folder |

Scene Design

| Tool | Description | |------|-------------| | analyze_scene | Spatial composition analysis — zones, relationships, design checks | | render_scene | Screenshot of the live 3D scene via the game's MCP camera | | compare_scene | Before/after snapshot diff | | position_camera | Compute optimal camera placement to frame one or more items | | record_video | Record a video fly-through from a CameraObject |

Live Game Connection

| Tool | Description | |------|-------------| | connect_to_game | Connect to a live game client via WebSocket bridge | | poll_game_events | Poll for events from the live game (Ctrl+Click items, Shift+Click locations) | | change_task_state | Activate, complete, or reset tasks in a live game | | get_runtime_data | Fetch live runtime variables and JS effector results |

The runtime bridge listens on ws://localhost:3099 (override with PORTALS_BRIDGE_PORT). Embedded/in-app browsers may not be able to reach localhost websockets — open the room in a regular local Chrome/desktop browser session for live-connection work.

AI-Generated Assets

| Tool | Description | |------|-------------| | text_to_3d_model | Generate a 3D model from text | | image_to_3d_model | Generate a 3D model from an image | | check_3d_model_task | Poll 3D model generation status | | list_generated_3d_models | List generated 3D models for the current user | | generate_ai_image | Generate an image from a text prompt | | list_generated_images | List generated images for the current user | | generate_ai_texture | Generate a seamless PBR texture from a text prompt | | list_generated_textures | List generated textures for the current user | | text_to_speech | Generate speech audio | | list_voices | List available text-to-speech voices | | generate_sound_effect | Generate sound effect audio | | generate_music | Generate an instrumental or vocal music track from a text prompt | | list_generated_sounds | List generated sounds for the current user |

Resources

The server bundles 160 docs:// resources covering item specs, workflow guides, recipes, harness grounding data, and more. Resources are served from the package — no external docs repo required.

| Category | URI Pattern | Count | Examples | |----------|-------------|-------|----------| | Reference specs | docs://ref/* | 40 | 26 item specs, systems, interactions, components | | Extended reference | docs://reference/* | 17 | Full API docs, cameras, movement, quests | | Python tools & libs | docs://python/* | 27 | apply_ops, query_room, portals_core, portals_effects | | Recipes | docs://recipes/* | 18 | Dice roll, board game, keypad, side-scroller, leaderboard, cutscene camera | | Workflows | docs://workflows/* | 13 | Scene design, validation, quality review, asset pipeline | | Indexes | docs://index/* | 5 | Items, triggers, effects, knowledge map | | Logic & scripting | docs://logic/* | 5 | JS reference, expressions, multiplayer, string variables | | Guides | docs://guide/* | 3 | Rules & conventions, workflow steps | | AI bootstrap | docs://ai/* | 4 | Execution policy, tool output contracts, tool capability manifest | | Harness grounding | docs://harness/* | — | Capabilities, limitations, patterns, response contract, eval fixtures | | Architecture | docs://architecture/* | — | Harness architecture assessment and migration plan | | Usage rules | docs://usage-rules | 1 | Tool roles & error handling | | Catalog | docs://catalog | — | JSON index of all resource URIs |

Testing

For the full Redis → matched server → WebGL/Core → browser runner → evidence loop, follow RUNTIME_HARNESS_RUNBOOK.md. A room write or Unity-editor result is not verified playability; the runbook defines the required runtime authority and evidence gates.

npm test
npm run build
npm run test:mcp-client

Harness-specific checks:

npm run check:harness
npm run check:harness-package
npm run eval:harness
npm run test:benchmark-health

Implementation Direction

See MCP_IMPLEMENTATION_GUIDE.md for the governing game-building north star, target architecture, public-tool admission rules, migration phases, evaluation gates, and anti-drift checklist. The objective is the best possible AI game-building experience; a smaller default tool surface is one means of improving model usability, not the product goal.

Shared Portals Build Kernel

The compatibility package name remains @portals/harness-core, but it now hosts the first pure, versioned Portals Build Kernel slice: capability grounding, complete game-plan validation, room authority, idempotent mutation/rollback receipts, evidence-bound final outcomes, and replayable inspect/plan/apply/playtest/refine/finalize state transitions. It also owns benchmark lifecycle contracts that keep provisional seeds, human calibration, holdouts, saturation, and creator outcomes machine-checkable without collapsing game quality into one score. Its internal phase coordinator persists stable invocation ids and requires exact recovery after interrupted side effects; the MCP-side immutable-file journal provides restart-safe compare-and-append storage. Every completed phase is also pinned to a canonical immutable artifact digest, and the verifier rejects detached inspection, plan, mutation, receipt, playtest, refinement, or finalization lineage. Repairs re-inspect and re-plan instead of mutating from stale pre-playtest assumptions. None of these internal phases add to the public MCP tool surface. The package is independently buildable under packages/harness-core:

The Build Kernel has two independent consumers. The in-game prompt-to-build adapter may use its own model to author phase artifacts. The standalone MCP never calls that adapter: the connected MCP client supplies the plan, mutation, test compilation, visual review, and repair artifacts directly. Both consumers share deterministic schemas, isolated mutation, Core playtesting, rollback, journals, and evidence-gated finalization without sharing model orchestration.

import { inspectGameForBuild, validateGameBuildPlan } from "@portals/harness-core";

The MCP package also exposes a compatibility subpath:

import { inspectGameForBuild, validateGameBuildPlan } from "portals-mcp/harness-core";

Use @portals/harness-core as the target dependency for product-native harness services once it is published or wired internally.

License

ISC