Connect to the Portals MCP

The fastest way to connect: hand this guide to your AI assistant. Paste the prompt below into Claude Code, Claude Desktop, Cursor, Codex, or any MCP client, and it reads the machine-readable version of this guide, adds the right config for your client, authenticates, and verifies the connection for you.

Prefer to set things up by hand? The full step-by-step guide is below.

Paste this prompt into your AI assistant:

Set up the Portals MCP server for me. Read https://portals.to/mcp/setup.md in full, then:
1. Add the Portals MCP config for my client (I'm using <name your client, e.g. Claude Code, Cursor, Codex CLI>).
2. Help me get my access key from https://portals.to/mcp.
3. Authenticate.
4. Run the verification steps and confirm it's connected by calling the authenticate and get_help tools, then report the results.

The Portals MCP server turns any MCP-capable AI assistant (Claude Code, Claude Desktop, Cursor, Codex, and others) into a Portals game designer. Once connected, your AI can create rooms, place items, wire up game logic, generate assets, and iterate on 3D spaces using natural language.

This guide gets you connected and verified in four steps. For the full tool and REST API reference, see the documentation and MCP & API.

• A Portals account. Sign in at portals.to (free to create).
• Node.js 18 or newer installed, which includes npx. The server runs via npx portals-mcp, so there's nothing to install separately.
• An MCP-capable client (Claude Code, Claude Desktop, Cursor, Codex CLI, or any other MCP client).

The MCP server authenticates to Portals with a personal access key. Go to portals.to/mcp and sign in. Your access key is shown on the page. Copy it.

Treat this key like a password: it's tied to your account. If it ever leaks, return to /mcp and click generate new key to revoke the old one and issue a fresh one.

Prefer not to copy-paste a key? Claude Code (and other interactive clients) can use the browser sign-in flow instead (see Step 3).

Pick your client below and apply the configuration. Replace your-access-key with the key from Step 1. Every client runs the exact same server (npx portals-mcp over stdio); only the config format and file location differ.

claude mcp add portals --env PORTALS_ACCESS_KEY=your-access-key -- npx portals-mcp

{
  "mcpServers": {
    "portals": {
      "command": "npx",
      "args": ["portals-mcp"],
      "env": {
        "PORTALS_ACCESS_KEY": "your-access-key"
      }
    }
  }
}

There are two ways to authenticate. You only need one.

Run through this checklist. If all three pass, you're connected.

• The portals server appears in your client. Check your client's MCP/tools list. Healthy: a portals server is listed and enabled, exposing its tools. Broken: it's missing, so re-check the config file and restart the client.
• authenticate confirms your account. Ask your AI to call the authenticate tool. Healthy: it confirms you're connected to your Portals account (it reports "already authenticated", or completes the browser sign-in). Broken: an auth error or a request to provide a key means the key is wrong or unset, so regenerate it at /mcp and re-check the env block.
• get_help returns guidance. Ask your AI to call get_help. Healthy: it returns setup and workflow guidance plus matching documentation resources. Broken: "tool not found" or "server not connected" means the server isn't running (see Troubleshooting).

• The server doesn't show up in my client. Fully restart the client after editing its config (Claude Desktop needs a complete quit-and-reopen). Confirm the JSON or TOML is valid; a stray comma or missing brace silently breaks the whole file.
• npx: command not found or the server won't launch. Node.js isn't installed or isn't on your PATH. Install Node.js 18+ from nodejs.org (it bundles npx), then open a fresh terminal (or fully restart your client) so the updated PATH is picked up.
• Authentication fails / "invalid access key". Regenerate your key at /mcp and paste the new value into your config's env block. Make sure there are no surrounding spaces or quotes, and that you replaced the literal your-access-key placeholder.
• The access key seems to be ignored. It must live in the env block ("PORTALS_ACCESS_KEY": "…" in JSON, env = { PORTALS_ACCESS_KEY = "…" } in TOML), not as a top-level field. Or skip the key entirely and use the browser flow (Step 3).
• Behavior seems stale after an update. npx can serve a cached build. The configs above use portals-mcp, which resolves the latest published version; if in doubt, run npx portals-mcp@latest once to refresh the cache.
• Claude Code rejects the add command. Keep --env after the server name and the -- before npx portals-mcp, e.g. claude mcp add portals --env KEY=value -- npx portals-mcp. Putting --env first makes the CLI read portals as an env pair.

A typical session bootstraps like this: call authenticate, then get_context with a description of what you want to build to pull targeted specs and recipes. For gameplay, resolve_gameplay_capability or plan_gameplay_mechanic check what's possible first. Then apply changes with apply_operations (scoped edits) or set_room_data (a full room snapshot).

The server exposes ~48 tools, grouped by area. The full reference lives in the documentation and API access pages.

• Auth & discovery: Sign in, pull targeted specs and recipes for your task, and check what's possible before building. (e.g. authenticate, get_help, get_context, resolve_gameplay_capability)
• Room management: Create rooms from templates, duplicate them, and inspect or query existing room data. (e.g. create_room, duplicate_room, inspect_room_data, query_room)
• Building: Apply scoped edits (add/modify/remove items, logic, and quests), or replace a full room snapshot. (e.g. apply_operations, set_room_data)
• Assets: Upload your own 3D models and images into a room. (e.g. upload_glb, upload_image)
• Scene design: Analyze spatial composition, frame cameras, and screenshot or record the live 3D scene. (e.g. analyze_scene, render_scene, position_camera, record_video)
• Live game: Connect to a running game over WebSocket to read events and drive task state in real time. (e.g. connect_to_game, poll_game_events, change_task_state)
• Generated assets: Generate 3D models, images, textures, speech, music, and sound effects with AI. (e.g. text_to_3d_model, generate_ai_image, text_to_speech, generate_music)