# Connect to the Portals MCP

## Have your AI set up your MCP connection

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.

Raw markdown for AI agents: https://portals.to/mcp/setup.md

Paste this prompt into your AI assistant:

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

## What it is

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](/documentation) and [MCP & API](/documentation/api).

## Prerequisites

- A Portals account. Sign in at [portals.to](https://portals.to) (free to create).
- [Node.js](https://nodejs.org) 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).

## Step 1: Get your access key

The MCP server authenticates to Portals with a personal access key. Go to [portals.to/mcp](/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](/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).

## Step 2: Add the server to your client

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 Code

Add the server with one terminal command, or commit a project-level `.mcp.json`.

**Terminal**

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

**.mcp.json (project root, optional)**

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

- Keep `--env` **after** the server name and the `--` before the command, otherwise the CLI reads `portals` as an env pair.
- Prefer the browser flow? Skip the `--env` flag and just run `claude mcp add portals -- npx portals-mcp`, then ask Claude to call `authenticate` (see Step 3).

### Claude Desktop

Edit `claude_desktop_config.json` via Settings → Developer → Edit Config, then fully restart Claude.

**claude_desktop_config.json**

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

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Claude Desktop only reloads MCP servers on a full quit-and-reopen, not a window close.

### Cursor

Add the same JSON to your global `~/.cursor/mcp.json` (all projects) or a per-project `.cursor/mcp.json`.

**~/.cursor/mcp.json  (or .cursor/mcp.json per project)**

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

- After saving, the server appears under Settings → MCP. Toggle it on if it isn't already enabled.

### Codex CLI

Codex uses TOML, not JSON. Add it with the CLI, or hand-edit `~/.codex/config.toml`.

**Terminal**

```bash
codex mcp add portals --env PORTALS_ACCESS_KEY=your-access-key -- npx portals-mcp
```

**~/.codex/config.toml**

```toml
[mcp_servers.portals]
command = "npx"
args = ["portals-mcp"]
env = { PORTALS_ACCESS_KEY = "your-access-key" }
```

- The table is `[mcp_servers.portals]`. Note that `mcp_servers` is snake_case and plural, unlike the JSON clients' `mcpServers`.

### Other clients

Any MCP client that speaks stdio accepts the standard `mcpServers` block. Adapt the wrapper to your client.

**Standard MCP config**

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

- The inner `command` / `args` / `env` object is universal across MCP clients. Only the file location and wrapper differ. Codex CLI is the notable exception (TOML, shown above).

## Step 3: Authenticate

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

### Access key (recommended for most clients)

Set `PORTALS_ACCESS_KEY` in the `env` block of your config (shown for each client in Step 2). The server reads it on startup and you're authenticated immediately, with no prompts.

You can also place the key in a `.env` file next to your project as `PORTALS_ACCESS_KEY=your-access-key`; the server picks it up automatically.

### Browser flow (great for Claude Code)

Leave the key out of your config and ask your AI to call the `authenticate` tool. It opens [portals.to/mcp](/mcp) in your browser; you sign in, and the key is sent straight back to the server over a local callback, so there's nothing to copy.

This is the smoothest path for interactive setups: the AI drives it, and you just confirm sign-in.

## Step 4: Verify it's working

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

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

## What you can do

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 a growing set of tools, grouped by area:

- **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`)_

Full tool and REST API reference: https://portals.to/documentation and https://portals.to/documentation/api.

---

_Last updated: June 23, 2026. Canonical page: https://portals.to/mcp/setup_