Connect a local MCP client

Prepare the local editor

Use Node.js 24 and pnpm 10. Clone the repository, install dependencies and run pnpm build:local once. Keep this checkout: the runtime and vendored fonts live there. This repository does not publish an npx squig package. No database, account or API key is required.

git clone https://github.com/pablostanley/squig.git
cd squig
pnpm install --frozen-lockfile
pnpm build:local

Generic stdio configuration

Replace the checkout and document paths with real absolute paths. Your MCP client launches the process and the companion also serves a local editor. Use Node directly; package-manager banners would corrupt stdio protocol output. The selected file is the only file exposed through tools. For a different canvas, configure a different file path and restart the server.

{
  "mcpServers": {
    "squig": {
      "command": "node",
      "args": [
        "--experimental-strip-types",
        "--disable-warning=MODULE_TYPELESS_PACKAGE_JSON",
        "--import",
        "/absolute/squig/scripts/register-loader.mjs",
        "/absolute/squig/scripts/squig.ts",
        "mcp",
        "/absolute/path/canvas.squig.json"
      ]
    }
  }
}

Codex configuration

The equivalent ~/.codex/config.toml entry uses command and args. Reconnect the MCP server after editing configuration. An absolute Node executable path can be used if your desktop client does not inherit your shell's PATH.

[mcp_servers.squig]
command = "node"
args = ["--experimental-strip-types","--disable-warning=MODULE_TYPELESS_PACKAGE_JSON","--import","/absolute/squig/scripts/register-loader.mjs","/absolute/squig/scripts/squig.ts","mcp","/absolute/path/canvas.squig.json"]

Find the live editor

Call squig_local_session to get documentId, filePath, editorUrl and mcpUrl. Send the full editorUrl to the user before drawing. It contains the local session token in its fragment; keep it private. Start with squig_documents and squig_get_document, then edit the existing document. Document responses also include the editor URL. File revisions are content tokens: pass the current value back, never increment it yourself.

An already running companion

pnpm squig serve /absolute/path/canvas.squig.json starts an editor and Streamable HTTP MCP at http://127.0.0.1:PORT/mcp. The default port is selected automatically; --port chooses a port. Connect agent in that editor supplies the actual address and session credential. HTTP clients send Authorization: Bearer with the token from the local editor link. Run only one companion per file; attach additional clients to its HTTP server instead of launching another stdio process.

Tools, resources and prompts

Local tools are squig_local_session, squig_catalog, squig_documents, squig_get_document, squig_edit_document, squig_replace_document, squig_history, squig_restore, squig_comment, squig_resolve_comment, squig_export_document, squig_measure_text and squig_render_document. There are no workspace creation, document deletion or key-rotation tools. The guide resource squig://guides/wireframing and wireframe-first prompt describe the workflow. All node types, grouping, layout, locks, variations and notes use the shared canvas engine.

Large results

Portable files may use up to 16 MiB including comments, but MCP responses are capped at 8 MiB including their protocol envelope. A larger tool result or validation error returns isError with status 413, filePath, editorUrl and the revision when available. The error says whether the operation completed or the request failed. If it completed, the edit remains saved. Read the selected filePath from disk and use squig_documents for the current revision before editing again. Do not retry the mutation blindly. For a large render, inspect the editor or export an image from the browser. Local HTTP reads can still retrieve the complete file.

Troubleshooting

A missing editor build means run pnpm build:local in the checkout. A file lock means another companion already owns this file; use that session or stop it first. A 409 means the file changed: read and reconcile before retrying. A stopped process makes its editor URL unavailable, but the file remains on disk. A missing or invalid HTTP token returns 401; an unexpected Host or browser Origin returns 403. Check that your agent runs on the same computer: a remote cloud agent cannot reach your loopback address.