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"]
    }
  }
}

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. |

First session

1. Ask your assistant to build something: "Create a mini golf course with a scoreboard." It will call authenticate (browser sign-in) the first time.
2. 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.
3. Edits land via apply_operations (scoped) or set_room_data (full snapshot); render_scene screenshots let it check its own work.

Tools

51 tools across authentication, marketplace assets, room building, scene design, live-game control, and AI asset generation.

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 | | 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 (full snapshot) | | apply_operations | Targeted ops: add_item, modify_item, remove_item, add_logic_task, clear_logic_tasks, add_quest, remove_quest, add_component |

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 |

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 ~148 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/* | 3 | Execution policy, tool output contracts | | 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

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

Shared Harness Core

The harness grounding layer is available as an independently buildable package under packages/harness-core:

import { resolveGameDevRequest } from "@portals/harness-core";

The MCP package also exposes a compatibility subpath:

import { resolveGameDevRequest } 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