---
title: How Local Codex Connects to the Canvas
description: Interaction between Canvas Agent, MCP, SSE, and browser canvas state
---

# How Local Codex Connects to the Canvas

Codex does not control the browser DOM or simulate mouse actions. A local `Canvas Agent` bridges Codex tools and the React state that owns the canvas.

```text
Codex or browser side panel
        ↓
Local Canvas Agent
        ↓
Browser canvas React state
```

## Two entry points

From a local Codex conversation, the `infinite-canvas` MCP tools call Canvas Agent's `/api/tools` endpoint. Common tools read canvas state and selection, create or update nodes, connect nodes, and start image or text generation.

From the browser side panel, the browser sends a turn to `/agent/codex/turn`. Canvas Agent starts or reuses `codex app-server --stdio` and provides the same MCP tools to that conversation. Canvas writes still follow the same path: `Codex → MCP → Canvas Agent → browser`.

## Browser connection and state

Canvas Agent listens on `http://127.0.0.1:17371` by default and generates a connection token. The browser opens an authenticated SSE connection:

```text
GET /events?token=xxx&clientId=xxx
```

The browser pushes snapshots to:

```text
POST /canvas/state?token=xxx&clientId=xxx
```

Snapshots contain the canvas ID and title, nodes, edges, selected node IDs, and viewport. Canvas Agent keeps the latest snapshot in memory, so tools read structured state rather than the DOM.

## Applying operations

For a node creation, Codex calls an MCP tool, Canvas Agent converts it to `canvas_apply_ops`, sends an SSE `tool_call`, and the browser applies operations such as `add_node`, `update_node`, `delete_node`, `connect_nodes`, `set_viewport`, and `select_nodes`. The browser posts the result to `/canvas/result`, which completes the MCP call.

Writes are automatically confirmed by default. Switch the side panel to manual confirmation to approve each write. The frontend also stores the snapshot before the latest Agent operation so it can be undone.

## Security boundary

- Canvas Agent binds to `127.0.0.1` by default.
- Browser connections require the generated token and are bound to the first accepted origin.
- Codex does not directly access the DOM or own the canvas state.
- The hosted website does not store the local Codex login, API keys, or local file permissions.
- The browser remains responsible for executing writes, approvals, undo, and permission controls.

In short, reads flow from browser snapshots through Canvas Agent and MCP to Codex; writes flow from Codex through MCP and SSE back to browser React state.
