Connect an AI agent

1. Which store holds the project. Projects in your Pascal account or organization use the hosted endpoint below. Projects made with the local Pascal CLI stay on your machine, and pascal editor starts their MCP service; no hosted account or API key is required. The two stores are separate: connecting the hosted server does not upload local projects. See Hosted MCP, local CLI, and the MCP package.
2. How the client signs in. Claude and the official Pascal Cursor connector sign in through the browser. Other hosted clients use an API key. See Connect your Pascal account.
3. How you check the result. Ask the agent to validate and save, then return the editorUrl Pascal reports. Open it, reload, and confirm the change is there. See Start an agent session.

https://editor.pascal.app/api/mcp

​

Connect your Pascal account

​

Create an API key

1. Sign in and open Settings.
2. In API keys, enter a name and choose the personal or organization workspace.
3. Click Create and copy the key immediately. Pascal does not show it again.
4. Open Connect an AI agent and choose your client for a copy-ready command.

​

Agent accounts and workspace invitations

pascal agent claim
pascal agent status --json

​

Exchange project files

​

Connect your client

​

Codex CLI

export PASCAL_API_KEY="paste_key_here"

codex mcp add pascal \
  --url https://editor.pascal.app/api/mcp \
  --bearer-token-env-var PASCAL_API_KEY

​

Claude Code

claude mcp add --scope user --transport http pascal https://editor.pascal.app/api/mcp \
  --header "Authorization: Bearer paste_key_here"

​

VS Code and GitHub Copilot

{
  "inputs": [
    {
      "type": "promptString",
      "id": "pascal-api-key",
      "description": "Pascal API key",
      "password": true
    }
  ],
  "servers": {
    "pascal": {
      "type": "http",
      "url": "https://editor.pascal.app/api/mcp",
      "headers": {
        "Authorization": "Bearer ${input:pascal-api-key}"
      }
    }
  }
}

​

Cursor

{
  "mcpServers": {
    "pascal-hosted": {
      "type": "http",
      "url": "https://editor.pascal.app/api/mcp",
      "auth": {
        "CLIENT_ID": "pascal-cursor",
        "scopes": ["openid", "profile", "offline_access", "scene:read", "scene:write"]
      }
    }
  }
}

​

Another mcp.json client

{
  "mcpServers": {
    "pascal": {
      "url": "https://editor.pascal.app/api/mcp",
      "headers": {
        "Authorization": "Bearer paste_key_here"
      }
    }
  }
}

​

Install from the MCP Registry

​

OpenClaw

​

Start an agent session

Use the Pascal MCP server. Read pascal://agent-guide, create a small one-bedroom
project, validate it, save it, and return the editorUrl from get_project_status.

​

Projects with live collaboration

• Saves go to the live draft. save_scene with saveMode: "checkpoint" is refused; save versions from the editor.
• Snapshot undo and redo are refused. Use the editor’s history, or make a targeted edit that reverses the change.

​

What MCP exposes

• Tools for projects, rooms, walls, openings, levels, stairs, roofs, furniture (on the floor, or hung on a wall, a ceiling or another item), scene queries, measurements, validation, collision checks, saving, and version status. They are the same tools Pascal’s in-app chat uses.
• A view of the scene (hosted server). view_scene returns a picture of the project from a view the agent chooses. Pass interior: { "zoneId": "zone_…" } to stand inside a room at eye height and look across it. Your open editor tab of the project renders the view for free, so keep it in front; a tab in the background answers with the editor link and the agent asks you to bring it forward. When no tab has the project open, Pascal renders the view in an editor on its own servers. Each view rendered there costs credits from the workspace that owns the project. The first one can take up to a minute to start: the tool waits for it, and only if it is still starting after about 45 seconds answers editor_starting for the agent to call again. Server views need an API key, a browser session, or an OAuth connection allowed to spend credits (Can spend credits under Connected apps). An agent account renders on Pascal’s servers only once it is claimed. To keep views free, turn off Render views on Pascal’s servers when no editor is open in the editor’s Settings → Preferences. Each answer carries a viewId naming that exact picture; pass it to generate_studio_media to render that view without taking it again. view_scene stays read-only.
• Catalog pictures. view_assets returns pictures of up to six catalog items by id (from search_assets or furnish_room), with each item’s size and the surface names paint accepts as role. Use it to check what an item looks like before placing it.
• Designed items. validate_design checks a procedural item recipe (schema: pascal://schema/design) without changing the scene, and reports diagnostics and measurements. place_design places one instance of a recipe that passes, on a level, wall or ceiling. Placement accepts version 1 recipes only for now.
• A design brief (hosted server). design_brief records what the request asks for, axis by axis. It lasts for the MCP session. Until one is written, place_items, furnish_room, place_in_room, add_object and place_design refuse with design_brief_required.
• Starting over. clear_scene empties a project on purpose, back to a site, a building and one level, when you ask the agent to start over. On the hosted server, any other write that would leave a project empty is refused, and the project stays as it was.
• Resources for the agent guide, current scene, scene summary, constraints, and the item catalog (on the hosted server, the published library the editor places from).
• Prompts for building from a brief, iterating from feedback, and renovations from photos when the client supports MCP sampling.
• Hosted services for discovering an installed plugin’s service access, retrieving site context, generating project media and reopening saved results. These use the same contracts as Ask Pascal and curated plugin agents. See Hosted services for costs and required access.

​

Common tool calls

​

Find and read nodes

{ "type": "window", "zoneId": "zone_kitchen" }

{ "parentId": "wall_north" }

{ "id": "wall_north" }

​

Paint surfaces

{ "queries": [{ "query": "white render" }, { "kind": "roofing" }, { "surface": "floor" }] }

{ "targets": ["wall_north", "wall_east"], "role": "exterior", "material": "library:siding-lap-white" }

​

Build stairs

{
  "x": 2,
  "z": 1,
  "rotation": 90,
  "layout": "l",
  "turn": "left",
  "railingStyle": "cable",
  "railingMaterial": "library:preset-nearblack"
}

{ "x": 0, "z": -0.5, "rotation": 180, "toLevelId": null, "height": 0.6, "width": 1.5 }

​

Build barrel and glazed roofs

{ "levelId": "level_ground", "roofType": "barrel", "barrelRise": 1.5, "barrelSegments": 16 }

{
  "roofType": "barrel",
  "roofSystem": "glazed",
  "barrelRise": 1.2,
  "glazing": {
    "along": { "layout": "fixed-spacing", "spacing": 1.2 },
    "frameColor": "#1f2328",
    "glassOpacity": 0.25
  }
}

{ "targets": ["roof_main"], "role": "glazing-frame", "color": "#1f2328" }

​

Set a gable’s overhang

{ "patches": [{ "op": "update", "id": "rseg_main", "data": { "gableOverhang": 0.6 } }] }

​

Read the site

{}

​

Choose the level

import { createPascalMcpServer, SceneBridge } from "@pascal-app/mcp";
import { createSceneOperations } from "@pascal-app/mcp/operations";

const bridge = new SceneBridge();
const operations = createSceneOperations({
  bridge,
  activeLevelId: () => myHost.viewedLevelId(),
});
const server = createPascalMcpServer({ bridge, operations });

​

Set the ground floor and add a basement

{ "levelId": "level_ground" }

​

Build objects in Blender

​

Convert a three.js design

{
  "payload": {
    "levels": [
      {
        "name": "Ground floor",
        "walls": [
          { "id": "n", "start": [-2, -2.5], "end": [2, -2.5], "height": 2.7, "thickness": 0.12 },
          {
            "id": "e", "start": [2, -2.5], "end": [2, 2.5], "height": 2.7, "thickness": 0.12,
            "openings": [{ "kind": "window", "along": 2.5, "width": 1.4, "height": 1.3, "sill": 0.9, "type": "casement" }]
          },
          {
            "id": "s", "start": [2, 2.5], "end": [-2, 2.5], "height": 2.7, "thickness": 0.12,
            "openings": [{ "kind": "door", "along": 1.2, "width": 0.9, "height": 2.1 }]
          },
          { "id": "w", "start": [-2, 2.5], "end": [-2, -2.5], "height": 2.7, "thickness": 0.12 }
        ],
        "rooms": [{ "name": "Bedroom", "seed": [0, 0], "floor": "#c8b89a" }],
        "items": [
          {
            "id": "bed",
            "name": "Bed",
            "category": "bed",
            "position": [0, 0, -1],
            "code": "export const mount = 'floor'\nexport default function build({ THREE }) {\n  const group = new THREE.Group()\n  const m = new THREE.MeshStandardMaterial({ color: '#8a6a4a' }); m.name = 'slot_body'\n  const b = new THREE.Mesh(new THREE.BoxGeometry(1.6, 0.5, 2), m); b.position.y = 0.25\n  group.add(b)\n  return group\n}"
          }
        ]
      }
    ],
    "notes": ["The rug was left out."]
  }
}

{
  "replace": true,
  "edits": [{ "in": "module", "find": "const wallHeight = 2.7", "replace": "const wallHeight = 3" }]
}

• Give every wall and item an id that is unique across all levels. A repeated id is refused with duplicate_source_id.
• A window with no type is written as fixed and cannot open.
• An item module allows at most 300k triangles and 32 materials.
• Pascal builds wall caps, floors and ceilings itself. Express baseboards as a wall’s skirting, floor finishes as a room’s floor or floorCode, and wall finishes as faceLeft/faceRight or a room’s wallCode. Don’t model them as slabs or items.
• A second conversion without replace: true is refused with conversion_exists.
• A building that already holds work not made by author_scene is never cleared (existing_design). Edit it with the native tools, or convert into another building.
• A stair in a level’s stairs climbs to the next level and cuts the floor above it. Never model a stair as an item.
• The module and adapter can each be up to 400,000 characters, and an adapter has 60 seconds to run.
• add_object can also describe an object in words (piece), which Pascal’s in-app chat uses. On the hosted MCP a piece is refused with pieces_unavailable, so send each item’s code.

​

Ask the Architect

Use the Pascal MCP server. Call ask_architect on project_your_project_id with the brief
"Add a covered porch along the front of the house", effort high and max_credits 50.
Poll get_architect_turn every 10 seconds until it ends, then summarize the reply.

{
  "brief": "Add a covered porch along the front of the house",
  "effort": "high",
  "project_id": "project_your_project_id",
  "max_credits": 50,
  "idempotency_key": "6f1c1f4e-2b7a-4f8e-9a51-3c0d6b9e7a21"
}

{ "id": "resp_..." }

​

Errors

• api_key_required: the connection’s credential can’t run the Architect. Reconnect with an API key.
• no_project: pass project_id, or call load_scene first.
• turn_not_found (404): no turn with this id that you can read, or a turn someone else started when you cancel it. project_not_found (404): no project with this id that your key can edit.
• insufficient_quota (402) and upgrade_required (403), as on the API page.
• turn_in_progress (409): another turn is already running on the project. Its id is in error.response_id.
• idempotency_mismatch (409): you sent this idempotency_key with a different request. Use a new key for a new request.
• invalid_input (400): an argument is malformed.

​

Check furniture dimensions

​

Hosted MCP, local CLI, and the MCP package

​

Local MCP with the Pascal CLI

npx @pascal-app/cli editor

claude mcp remove --scope user pascal

pascal mcp setup codex

{
  "mcpServers": {
    "pascal": {
      "command": "pascal",
      "args": ["mcp", "connect"]
    }
  }
}

​

Serve a plugin’s agent tools

import type { McpServer } from "@modelcontextprotocol/server";
import type { SceneOperations } from "@pascal-app/mcp/operations";
import { registerOperationTool } from "@pascal-app/mcp/tools/shared-tools";
import { signageAgentTools } from "@acme/pascal-signage/agent-tools";
import { signageAgentOperations } from "@acme/pascal-signage/agent-operations";

export function registerSignageTools(server: McpServer, operations: SceneOperations) {
  for (const tool of signageAgentTools.tools) {
    const operation = signageAgentOperations[tool.name];
    if (tool.runsIn !== "operation" || !operation) continue;
    registerOperationTool(server, operations, {
      contract: tool,
      operation,
      annotations: { readOnlyHint: false, destructiveHint: false },
    });
  }
}

​

Troubleshooting

• Unauthorized — confirm the Bearer prefix, credential scope, and that the client sends the expected header. Reuse a valid existing key; replace it only when revoked or lost. Reconnecting does not require another agent account. A suspended account’s sessions, API keys and OAuth connections all answer 401 with “This account cannot be used right now. Contact support.”
• The project is missing in the browser — confirm that the key belongs to the same user or organization you opened in Pascal. Self-registered agents own a separate workspace.
• The browser looks stale or empty — ask the agent to call get_project_status, load the correct project, save a draft, and return the reported editorUrl.
• A session expired or moved servers (HTTP 404 / MCP -32001; formerly HTTP 419) — Every connection (API key, OAuth or browser session) keeps its session in Pascal’s database, so any server answers it. A session lasts up to 24 hours, and ends sooner after 2 hours without a request. An expired, closed or revoked session still needs recovery. Create a fresh MCP client and transport once, then call get_project_status with the known project ID to load its persisted draft. Compare the version and graph hash before continuing. Do not replay an edit whose outcome is uncertain; check the saved scene first. If the replacement session also fails, stop reconnecting and use an authenticated Scene API read to confirm saved work. The error reports executedOnThisInstance: false for this HTTP attempt and lastMutationCommitState: "unknown" for earlier calls. Unbound edits and undo history cannot be recovered from a replacement session. The TypeScript MCP SDK 1.30 client surfaces this error without automatically reinitializing; a new transport must not reuse the old session ID.
• Session limits — one person can hold 5 open sessions. A sixth connection closes one of your sessions that isn’t running a tool, preferring one with no project loaded, then the least recently used. If all 5 sessions are running a tool, the sixth connection is refused: initialize answers HTTP 429 with Retry-After: 5 and “All 5 Pascal connections are running a tool. Retry when one finishes.” A closed session’s next request answers 404; initialize again, without signing in again. A session that ended (closed, evicted or idle) always answers 404; only a call whose outcome is uncertain answers 409, so check the saved scene before repeating it. DELETE on a session that already ended answers 204. Send DELETE when you’re done to free the slot.
• A repeated tool call ran twice — on durable sessions a JSON-RPC id is not an idempotency key. A tools/call re-sent under the same id replays its first answer only if it is the session’s latest request and finished less than 5 minutes ago; otherwise it runs again. To retry a mutation safely, send the same _meta["app.pascal/client-operation-id"].
• “Another tool is running” (HTTP 409) — one tool runs at a time per session. ping and tools/list, prompts/list, resources/list and resources/templates/list answer while a tool runs; tools/call, resources/read and prompts/get wait their turn.
• A session credential or authority changed (HTTP 403) — initialize a new session after switching API keys, browser sessions, workspaces, or agent authority. A session belongs to the exact credential that created it, even when two keys share an owner.
• Photo tools fail — vision tools require an MCP client that supports sampling.
• Service permission denied — check the credential, project, installed plugin and membership in Hosted services. On an OAuth connection, spending_not_allowed means the person hasn’t turned on Can spend credits for it under Connected apps.