# Pascal for agents

> How and when an AI agent should use Pascal Editor (https://editor.pascal.app).

## When to use Pascal

Reach for Pascal when the job is an editable 3D building model that a person will open, check and keep working on:

- Build a house, apartment, office or single room from a description, a floor plan, a photo or a sketch, and hand back a link the person can open in the editor.
- Read or change an existing Pascal project the person shares: walls, slabs, levels, zones, roofs, stairs, doors, windows, furniture and materials.
- Check whether a piece of furniture fits a measured room (footprint and clearance), with the furniture-fit skill or the no-sign-in calculator.
- Work with a Pascal Capture (iOS) room scan already in a project. Capture tools read existing scans; they cannot start one.
- Render images or videos of a scene with Studio, or pull site context for an address. These are paid services with a credit ceiling you set per call.
- Embed a live, interactive 3D viewer of a published project in another page.

Pascal is not the right tool for structural engineering sign-off, permit drawings, building-code compliance or construction cost estimates. Site results report sources and gaps; they are not a guarantee of buildability.

## Instructions for agents

1. Use the person's own Pascal identity for work in their projects: browser OAuth where the client supports it, otherwise an API key the person creates in Settings. Create a separate agent account only when the task explicitly calls for separate private work.
2. Connect to the hosted MCP server at https://editor.pascal.app/api/mcp (Streamable HTTP) and read the pascal://agent-guide resource first. The Scene API (https://editor.pascal.app/api/openapi.json) offers the same projects over REST and server-sent events.
3. Keep local and hosted work apart. A local CLI scene (npx @pascal-app/cli editor) stays in the local store; connecting the hosted server does not upload it.
4. Validate and save before you report success, then return the editorUrl that get_project_status reports. Do not invent project URLs.
5. Paid tools take a maxCredits ceiling. Pascal computes the price and refuses a charge above it; ask the person before spending.
6. Errors are JSON with a machine-readable code. On 429, wait the Retry-After seconds; every response reports the remaining budget in RateLimit headers. On 401, follow the resource_metadata in WWW-Authenticate. On 403 insufficient_scope, ask the person to reconnect with the scope it names.
7. A JSON export is not a GLB file; MCP export_glb is unsupported. Publish the project and download its 3D file through the Pascal API instead.

## Interfaces

- **Hosted MCP** — https://editor.pascal.app/api/mcp, Streamable HTTP. Tools to create, inspect, edit, validate and save scenes, plus project files and hosted services. Server card: https://editor.pascal.app/.well-known/mcp/server-card.json.
- **Scene API** — REST and server-sent events for project reads, writes and live events. OpenAPI 3.1: https://editor.pascal.app/api/openapi.json.
- **Pascal API (v1)** — the Architect over the OpenAI Responses and Chat Completions formats, at https://editor.pascal.app/api/v1. Guide: https://editor.pascal.app/docs/developers/api.
- **Agent skills** — the public pascal-3d and furniture-fit skills, indexed at https://editor.pascal.app/.well-known/agent-skills/index.json.
- **Local editor** — `npx @pascal-app/cli editor` runs the open-source editor on your machine; `pascal mcp connect` adds its local MCP server to a client.
- **In the browser** — pages on editor.pascal.app register WebMCP tools on `document.modelContext` for browser agents.
- **Open source** — the viewer, editor, scene engine and MCP server are MIT-licensed at https://github.com/pascalorg/editor and published on npm as @pascal-app/*.

## Guides

- Connect an AI agent: https://editor.pascal.app/docs/developers/mcp
- Connect Claude: https://editor.pascal.app/docs/developers/claude
- Pascal API (v1): https://editor.pascal.app/docs/developers/api
- Errors, rate limits and versioning: https://editor.pascal.app/docs/developers/errors
- Agent discovery: https://editor.pascal.app/docs/developers/agent-discovery
- Agent skills: https://editor.pascal.app/docs/developers/agent-skills