Connect an AI agent

Pascal exposes a hosted Model Context Protocol server that lets an AI agent create, inspect, edit, validate, and save 3D building projects. Changes use the same project store as the browser editor, so you can watch the result and continue editing it in Pascal. For projects stored by the local Pascal CLI, pascal editor starts MCP automatically. The Pascal agent skills 0.1.7 Claude Code plugin supplies pascal mcp connect automatically; other clients configure the same connector once. No hosted account or API key is required. Jump to local MCP. The hosted endpoint is:

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

Create an API key

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

Use a key created by the same Pascal user or organization that owns the projects you want the agent to edit. Agent self-registration creates a separate account, so its projects do not automatically appear in your current browser account.

Treat the API key like a password. Keep it out of source control, chat transcripts, screenshots, and shell history. Revoke a key from Settings when it is no longer needed.

Agent accounts and workspace invitations

Use your existing user/workspace key when an agent is helping with your projects. An autonomous agent can create its own private account through POST /api/auth/agent/register when the requested task authorizes it. Registration returns userId, a persistent agentId, an API key, and starterProjectId. Keep the key in the host’s secret store and reuse the identity across sessions. Agent accounts have no email address or browser login. The Pascal CLI (npm install --global @pascal-app/cli) includes these commands for hosts where the agent key is available as PASCAL_API_KEY:

pascal agent claim
pascal agent status --json

The claim command requests a 15-minute code and opens a prefilled claim page. Use --no-open on a headless host or --json for structured output without opening a browser. A new request supersedes the previous code. Direct integrations can use POST /api/auth/agent/claim/start and GET /api/auth/agent/status instead. After the person completes the handoff, run pascal agent status --json or call GET /api/auth/agent/status with the same Bearer key. A successful response confirms that the key is active and reports only the agent ID, autonomous/delegated mode, claim state, and whether the key is organization-scoped. It does not disclose who claimed the agent or expose credential metadata. Claiming links identities; it does not transfer projects, grant either identity access to the other’s private work, or link local CLI projects. This is separate from the planned OAuth/device login. Verify the intended recipient’s project access before returning a handoff. To join a workspace, obtain a single-use agent invite link from a workspace manager. Send the opaque token or the full invite URL in the body of POST /api/auth/agent/invites/redeem. An agent that already has an API key sends it with this request and keeps its existing identity. Without a key, redemption creates another agent account. Invite-link creation requires a human manager session; new agents cannot receive email-addressed invitations. External MCP clients currently use API keys. The endpoint also accepts an existing Pascal browser session. OAuth and CLI device login are not available yet.

Connect your client

Replace paste_key_here with the key you just created.

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

Register the server once, then start Codex from a terminal where PASCAL_API_KEY is set. Export the variable again in each new terminal, or supply it through your existing shell or secret-manager configuration. Codex stores the variable name, not its value. Remove commands containing the actual key from shell history.

Claude Code

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

This saves Pascal and its API key in Claude Code’s user configuration, so the connection is available when you start Claude in another project. To keep it local to the current project instead, replace --scope user with --scope local. The command contains the actual key after replacement; remove it from shell history after setup and keep Claude Code’s configuration private.

This command connects hosted Pascal projects. If Pascal agent skills 0.1.7 is installed, open /mcp and disable its local server, plugin:pascal-agent-skills:pascal, before adding this hosted connection. The plugin server reads local CLI projects; this server reads the account or organization that issued the API key.

VS Code and GitHub Copilot

Add Pascal to VS Code opens the install prompt in VS Code, where Copilot agent mode can then use the Pascal tools. VS Code asks for the API key the first time it starts the server and keeps it in its own secret storage, so the key is never written into the configuration file. To configure it by hand instead, add the server to .vscode/mcp.json for one workspace, or to your user configuration through MCP: Open User Configuration:

{
  "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 or another `mcp.json` client

Add this server to .cursor/mcp.json or your client’s equivalent configuration:

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

Prefer an environment-variable or secret-store interpolation supported by your client instead of committing a literal key.

OpenClaw

Use OpenClaw’s current skill and integration documentation to configure a compatible MCP client or an explicit HTTP workflow. Skill installation alone does not connect a hosted server or authorize account creation. The portable Pascal skills and their required tools are maintained in the public editor repository.

Start an agent session

Ask the client to connect to Pascal and read the pascal://agent-guide resource first. That guide describes the expected project workflow, semantic construction tools, validation, saving, and final handoff. An example first request is:

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.

Agents should return the editorUrl produced by Pascal tools rather than constructing a URL themselves. Open that URL to inspect the browser-visible draft.

What MCP exposes

The server provides:

Tools for projects, rooms, walls, openings, levels, roofs, furniture, scene queries, measurements, validation, collision checks, saving, and version status.
Resources for the agent guide, current scene, scene summary, constraints, and a small built-in item catalog.
Prompts for building from a brief, iterating from feedback, and renovations from photos when the client supports MCP sampling.

Use semantic tools such as create_room, add_door, add_window, and furnish_room before reaching for raw scene patches. Finish with validate_scene, verify_scene, save_scene, and get_project_status.

Check furniture dimensions

For a bounded first task, supply measured room dimensions, item dimensions, placement, and the clearances you want checked. Ask the agent to load the authorized project, confirm units, use the measurement and footprint collision tools, and return a report with the source revision, measured distances, conflicts, and missing evidence. A plan footprint does not prove height clearance, door swing, a delivery path, or exact mesh intersection. An undimensioned photo or incomplete scan may be insufficient for a fit decision. The export_glb MCP tool is not implemented; a JSON export or a preview must not be presented as a downloadable GLB.

Hosted MCP, local CLI, and the MCP package

These entry points share the same tools but use different project stores:

Entry point	Use it for	Data location
Hosted MCP at `editor.pascal.app/api/mcp`	Let an agent edit projects owned by a Pascal account or organization	Pascal’s hosted project store
`@pascal-app/cli`	Run the local editor and its managed MCP service together	`~/.pascal/data/pascal.db`
`@pascal-app/mcp`	Embed or run the open-source MCP server for a local/custom host	Local SQLite or a host-provided store

Local MCP with the Pascal CLI

Start Pascal normally. The editor and authenticated MCP service start together on collision-free loopback ports:

npx @pascal-app/cli editor

The MCP service is already running. The Pascal agent skills 0.1.7 Claude Code plugin already includes the stable stdio connector. Keep pascal on the PATH used to launch Claude Code and do not also run pascal mcp setup claude. If a previous manual setup created a user-scoped entry, remove it before reloading or restarting Claude Code:

claude mcp remove --scope user pascal

Use /mcp to remove or disable project- or local-scoped duplicates so only plugin:pascal-agent-skills:pascal remains active. Local plugin use needs no account or API key. Codex still needs the local connector configured once:

pascal mcp setup codex

If you use Claude Code without the plugin, configure the same connector manually with pascal mcp setup claude instead. Never keep the manual and plugin-provided Pascal servers active together. For a JSON-based client:

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

The setup command uses the client’s official CLI and never overwrites an existing Pascal entry. The connector discovers the running service and starts Pascal automatically when it is stopped. Use pascal mcp status, pascal mcp config, or pascal doctor to inspect the integration. A typical existing-project workflow is list_scenes → load_scene → semantic editing tools → validate_scene and verify_scene → save_scene → get_project_status. The returned editorUrl opens the same local project. Use the standalone @pascal-app/mcp package directly only when embedding Pascal tools in another application or providing a custom scene store.

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.
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) — hosted session state is currently process-local. 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.
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.

For direct HTTP integrations, use the OpenAPI document. MCP clients should use the native Streamable HTTP endpoint instead of reimplementing MCP over OpenAPI.

Integrate

Extend Pascal

Connect an AI agent

Create an API key

Agent accounts and workspace invitations

Connect your client

Codex CLI

Claude Code

VS Code and GitHub Copilot

Cursor or another `mcp.json` client

OpenClaw

Start an agent session

What MCP exposes

Check furniture dimensions

Hosted MCP, local CLI, and the MCP package

Local MCP with the Pascal CLI

Troubleshooting

​Create an API key

​Agent accounts and workspace invitations

​Connect your client

​Codex CLI

​Claude Code

​VS Code and GitHub Copilot

​Cursor or another mcp.json client

​OpenClaw

​Start an agent session

​What MCP exposes

​Check furniture dimensions

​Hosted MCP, local CLI, and the MCP package

​Local MCP with the Pascal CLI

​Troubleshooting

Create an API key

Agent accounts and workspace invitations

Connect your client

Codex CLI

Claude Code

VS Code and GitHub Copilot

Cursor or another `mcp.json` client

OpenClaw

Start an agent session

What MCP exposes

Check furniture dimensions

Hosted MCP, local CLI, and the MCP package

Local MCP with the Pascal CLI

Troubleshooting