> ## Documentation Index
> Fetch the complete documentation index at: https://editor.pascal.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect an AI agent

> Connect Claude Code, Codex, Cursor, OpenClaw, or another MCP client to Pascal projects.

Pascal exposes a hosted [Model Context Protocol](https://modelcontextprotocol.io/)
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.
Configure a local client once to launch `pascal mcp connect`; no hosted account or API
key is required. [Jump to local MCP](#local-mcp-with-the-pascal-cli).

The hosted endpoint is:

```text theme={null}
https://editor.pascal.app/api/mcp
```

## Create an API key

1. Sign in and open [Settings](https://editor.pascal.app/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.

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.

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

## Connect your client

Replace `paste_key_here` with the key you just created.

### Codex CLI

```bash theme={null}
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
```

Start a new Codex session after adding the server.

### Claude Code

```bash theme={null}
export PASCAL_API_KEY="paste_key_here"

claude mcp add --transport http pascal https://editor.pascal.app/api/mcp \
  --header "Authorization: Bearer $PASCAL_API_KEY"
```

### Cursor or another `mcp.json` client

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

```json theme={null}
{
  "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

```bash theme={null}
openclaw mcp set pascal \
  '{"url":"https://editor.pascal.app/api/mcp","transport":"streamable-http","headers":{"Authorization":"Bearer paste_key_here"}}'
```

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

A reliable first request is:

```text theme={null}
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`.

## 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`](/docs/developers/local-editor)                                   | Run the local editor and its managed MCP service together            | `~/.pascal/data/pascal.db`            |
| [`@pascal-app/mcp`](https://github.com/pascalorg/editor/tree/main/packages/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:

```bash theme={null}
npx @pascal-app/cli editor
```

The MCP service is already running. MCP clients use a stable stdio connector so their
configuration does not contain the dynamic port or Pascal's private local token:

```bash theme={null}
pascal mcp setup codex
pascal mcp setup claude
```

For a JSON-based client:

```json theme={null}
{
  "mcpServers": {
    "pascal": {
      "command": "pascal",
      "args": ["mcp", "connect"]
    }
  }
}
```

The setup command uses each 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** — create a new key, confirm the `Bearer` prefix, and verify that the
  client actually sends the header.
* **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** — reconnect the MCP client, then call `get_project_status` with
  the project ID to bind the new session.
* **Photo tools fail** — vision tools require an MCP client that supports sampling.

For direct HTTP integrations, use the
[OpenAPI document](https://editor.pascal.app/api/openapi.json). MCP clients should use
the native Streamable HTTP endpoint instead of reimplementing MCP over OpenAPI.