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

# Use Modellix Agent Canvas in Coding Agents

> Install the Modellix Agent Canvas local stdio MCP plugin in Codex, Cursor, Claude Code, or OpenCode for visual image work, HTML drafts, and presentations.

[Modellix Agent Canvas](https://github.com/Modellix/modellix-agent-canvas) is a local, workspace-bound `stdio` MCP plugin for visual AI work. It brings an Excalidraw infinite canvas, Modellix image generation and editing, paid-operation confirmation, durable task recovery, HTML drafts, presentations, and project-local persistence into one workspace.

Canvas runs on your machine. It does **not** require a deployed Canvas service. Hosts with [MCP Apps](https://modelcontextprotocol.io/) can embed the full canvas; other compatible hosts open the same server through a short-lived loopback page.

<Note>
  Agent Canvas is separate from the [Modellix Plugin](/ways-to-use/plugin), which teaches agents to run media tasks through `modellix-cli` or the REST API. Use Agent Canvas when you want a visual workspace; use the Plugin or [Skill](/ways-to-use/skill) when you want CLI-first image, video, and speech generation.
</Note>

## What You Get

* **Infinite canvas** — text, shapes, lines, arrows, freehand drawing, frames, images, grouping, locking, layers, alignment, and undo/redo
* **Multi-page projects** — create, rename, duplicate, reorder, and delete pages with independent viewports
* **Image placeholders** — reserve a target area before generation; results replace the placeholder and stay undoable
* **Image generation and editing** — text-to-image, single-image edit, ordered multi-image references, transparent backgrounds, and 1–4 outputs
* **Paid-operation safety** — prepare is free; submit needs explicit one-time confirmation; unknown submissions are never retried automatically
* **Durable tasks** — task IDs and local results persist so work can continue after the host or browser closes
* **HTML drafts and presentations** — sandboxed HTML preview, slide layouts, presentation mode, and PNG-sequence export
* **Local credentials** — API keys use the `modellix-cli` system credential store and are never written to chat, MCP arguments, URLs, or project files

Source and release notes: [GitHub](https://github.com/Modellix/modellix-agent-canvas) · npm [`@modellix/agent-canvas`](https://www.npmjs.com/package/@modellix/agent-canvas)

## Requirements

* Node.js `^20.19.0` or `>=22.12.0`, with npm on `PATH`
* Network access to `https://api.modellix.ai` and `https://registry.npmjs.org`
* A Modellix API key from the [Modellix Console](https://www.modellix.ai/console/api-key)

Install from the host once. Codex, Cursor, and Claude Code load the plugin from Git or Marketplace and resolve the pinned npm runtime in the background. OpenCode and generic MCP hosts add the npm-backed MCP once. You do **not** run a second global CLI install.

Verify the runtime on any host:

```bash theme={null}
npx -y --package @modellix/agent-canvas modellix-agent-canvas --doctor
```

## Install

Choose one path for your host.

<Tabs>
  <Tab title="Codex">
    ```bash theme={null}
    codex plugin marketplace add Modellix/modellix-agent-canvas
    codex plugin add modellix-agent-canvas@modellix
    ```

    You can also install **Modellix Agent Canvas** from `/plugins` or the desktop Plugins directory. Start a new task after installation so the session loads the skills and MCP tools.

    On first use, the Codex adapter caches the pinned npm runtime in a user-local directory. Warm starts reuse that cache without a persistent `npx` wrapper.
  </Tab>

  <Tab title="Cursor">
    In Cursor 2.6+, run:

    ```text theme={null}
    /add-plugin modellix-agent-canvas
    ```

    For a GitHub or local checkout, open **Customize → Plugins → + Add** and select the repository root. Cursor reads `.cursor-plugin/marketplace.json` and offers **Modellix Agent Canvas** from the `modellix` personal marketplace.

    For a direct MCP setup, add the repository `mcp.json` (or an equivalent `stdio` entry that runs `modellix-agent-canvas` with `--host cursor --supports-mcp-apps true`). Cursor supplies the active workspace through MCP Roots—do **not** pass a literal `${workspaceFolder}` argument.

    Reload Cursor and confirm `modellix-agent-canvas` is connected in MCP settings.
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    claude plugin marketplace add Modellix/modellix-agent-canvas
    claude plugin install modellix-agent-canvas@modellix
    ```

    After enabling or upgrading, run `/reload-plugins`, then `/mcp` to verify the connection.
  </Tab>

  <Tab title="OpenCode">
    Merge the server from [`adapters/opencode/opencode.json`](https://github.com/Modellix/modellix-agent-canvas/blob/main/adapters/opencode/opencode.json) into your project `opencode.json`. OpenCode V2 beta users should merge [`adapters/opencode/opencode-v2.json`](https://github.com/Modellix/modellix-agent-canvas/blob/main/adapters/opencode/opencode-v2.json) instead.

    Example for the stable OpenCode shape:

    ```json theme={null}
    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "modellix-agent-canvas": {
          "type": "local",
          "command": [
            "npx",
            "-y",
            "--package",
            "@modellix/agent-canvas",
            "modellix-agent-canvas",
            "--host",
            "opencode",
            "--supports-mcp-apps",
            "false"
          ],
          "cwd": ".",
          "enabled": true
        }
      }
    }
    ```

    Restart OpenCode after saving. Prefer pinning the exact npm version published in the [repository README](https://github.com/Modellix/modellix-agent-canvas) when you need a fixed runtime.
  </Tab>

  <Tab title="Other MCP Hosts">
    Configure a local `stdio` MCP server:

    ```json theme={null}
    {
      "command": "npx",
      "args": [
        "-y",
        "--package",
        "@modellix/agent-canvas",
        "modellix-agent-canvas",
        "--host",
        "generic",
        "--supports-mcp-apps",
        "false",
        "--project-dir",
        "/absolute/path/to/project"
      ]
    }
    ```

    `--project-dir` must be an existing real absolute directory (not a symlink). One MCP process binds to one workspace.
  </Tab>
</Tabs>

## Host Compatibility

| Host                  | Local MCP         | Canvas Surface                       |
| --------------------- | ----------------- | ------------------------------------ |
| Codex                 | `stdio`           | MCP Apps widget, with local fallback |
| Cursor 2.6+           | `stdio`           | MCP Apps                             |
| Claude Code           | `stdio`           | Short-lived local page               |
| OpenCode              | Local MCP command | Short-lived local page               |
| Other stdio MCP hosts | Local MCP command | Short-lived local page               |

Full protocol details live in the repository [host compatibility](https://github.com/Modellix/modellix-agent-canvas/blob/main/docs/host-compatibility.md) guide.

## First Use and API Key

After install, ask your agent to open Canvas for the active project:

```text theme={null}
get_modellix_canvas_status with refresh true and the absolute workspace path
open_modellix_canvas with the same absolute workspace path
```

Codex skills often supply `workspacePath` automatically. The path must be a real absolute directory, and one MCP session binds to one workspace.

If status is `missing` or `invalid`, Canvas shows a password field in its credential card. The form is an isolated, one-time loopback page that expires after five minutes. Submitting the key validates it through the bundled CLI, stores it in the system credential store, and refreshes status. The key never enters Canvas state or MCP tool arguments.

Credential resolution order:

1. Reuse a valid credential already saved by `modellix-cli`
2. Otherwise enter a key in the Canvas credential card

<Warning>
  Never put an API key in chat, MCP config, command-line arguments, repository files, screenshots, project backups, or task reports. Canvas does not store keys in `localStorage`, `sessionStorage`, or IndexedDB.
</Warning>

## Typical Image Workflow

Paid image work follows a prepare → confirm → submit → finalize path:

1. **Prepare** — `prepare_modellix_image_task` resolves references, selects a model, and returns routing reason, effective specification, limitations, and estimated total cost. Prepare is free and does not create a paid task.
2. **Confirm** — review the model, quantity, warnings, and cost in the UI or agent reply.
3. **Submit** — after explicit approval, `submit_modellix_image_task` submits the unchanged intent with the same confirmation fingerprint.
4. **Poll** — `get_modellix_image_task` tracks registered tasks only. If status is `SUBMISSION_UNKNOWN`, query only—do not automatically resubmit.
5. **Finalize** — `finalize_modellix_image_task` downloads assets into the project and places them on the canvas.

Prompts and input images are sent to Modellix only after you confirm the paid task. Completed outputs are downloaded into project assets so you are not dependent on expiring remote URLs.

## Useful MCP Tools

Agent-facing tools include:

| Tool                                                               | Purpose                                                   |
| ------------------------------------------------------------------ | --------------------------------------------------------- |
| `get_modellix_canvas_status`                                       | Check runtime and credential status                       |
| `start_modellix_api_key_setup`                                     | Open the short-lived local key form                       |
| `open_modellix_canvas`                                             | Open the canvas for a workspace                           |
| `get_canvas_context`                                               | Read canvas context for the agent                         |
| `create_canvas_page` / `rename_canvas_page` / `delete_canvas_page` | Manage pages                                              |
| `prepare_modellix_image_task`                                      | Free prepare step with cost and routing                   |
| `submit_modellix_image_task`                                       | Paid submit after confirmation                            |
| `get_modellix_image_task`                                          | Poll a registered task                                    |
| `list_modellix_canvas_tasks`                                       | List local canvas tasks                                   |
| `finalize_modellix_image_task`                                     | Download and place results                                |
| `cleanup_modellix_canvas_uploads`                                  | Clean terminal temporary uploads (`confirmCleanup: true`) |

## Project Data

Each bound workspace stores Canvas data under:

```text theme={null}
.modellix/canvas/
├── project.json
├── pages/
├── assets/
├── tasks/
├── recovery/
└── locks/
```

Uninstalling the plugin does **not** delete this directory or shared system credentials. Back up project data before you remove it. To remove a stored CLI profile, check `modellix-cli auth status --json`, then run `modellix-cli auth logout --profile <PROFILE>` only when you intend to drop that credential.

## Upgrade and Uninstall

| Host                   | Upgrade                                                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------ |
| Codex                  | `codex plugin marketplace upgrade modellix`, then update `modellix-agent-canvas@modellix`  |
| Claude Code            | `claude plugin marketplace update modellix`, update from `/plugin`, then `/reload-plugins` |
| Cursor                 | Update from the plugin page, or bump the exact npm version in direct MCP config            |
| OpenCode / generic MCP | Bump the exact npm package version and restart the host                                    |

## Troubleshooting

| Problem                               | What to Do                                                                                                                   |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| MCP server does not connect           | Run `npx -y --package @modellix/agent-canvas modellix-agent-canvas --doctor`, confirm Node.js version, then reload the host. |
| Canvas asks for an API key            | Enter the key in the Canvas credential card, or reuse a valid `modellix-cli` profile. Do not put the key in MCP config.      |
| `${workspaceFolder}` errors in Cursor | Remove that argument. Cursor binds the workspace through MCP Roots.                                                          |
| Paid task status is unknown           | Query with `get_modellix_image_task` or check account activity. Do not automatically resubmit.                               |
| Wrong or empty workspace              | Pass a real absolute project path as `workspacePath` / `--project-dir`. One MCP process binds to one workspace.              |

## Next Steps

<CardGroup cols={2}>
  <Card title="Plugin" icon="puzzle" href="/ways-to-use/plugin">
    CLI-first media generation for coding agents.
  </Card>

  <Card title="Skill" icon="wrench" href="/ways-to-use/skill">
    Install the Modellix Agent Skill on its own.
  </Card>

  <Card title="REST API" icon="code" href="/ways-to-use/api">
    Call Modellix media endpoints directly.
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/Modellix/modellix-agent-canvas">
    Source, host adapters, and release details.
  </Card>
</CardGroup>