Use Modellix Agent Canvas in Coding Agents

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 can embed the full canvas; other compatible hosts open the same server through a short-lived loopback page.

Agent Canvas is separate from the Modellix 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 when you want CLI-first image, video, and speech generation.

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 · npm @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

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:

npx -y --package @modellix/agent-canvas modellix-agent-canvas --doctor

Install

Choose one path for your host.

Codex
Cursor
Claude Code
OpenCode
Other MCP Hosts

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.

In Cursor 2.6+, run:

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

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.

Merge the server from adapters/opencode/opencode.json into your project opencode.json. OpenCode V2 beta users should merge adapters/opencode/opencode-v2.json instead.Example for the stable OpenCode shape:

{
  "$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 when you need a fixed runtime.

Configure a local stdio MCP server:

{
  "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.

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

First Use and API Key

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

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:

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

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.

Typical Image Workflow

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

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.
Confirm — review the model, quantity, warnings, and cost in the UI or agent reply.
Submit — after explicit approval, submit_modellix_image_task submits the unchanged intent with the same confirmation fingerprint.
Poll — get_modellix_image_task tracks registered tasks only. If status is SUBMISSION_UNKNOWN, query only—do not automatically resubmit.
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:

.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

Plugin

CLI-first media generation for coding agents.

Skill

Install the Modellix Agent Skill on its own.

REST API

Call Modellix media endpoints directly.

GitHub Repository

Source, host adapters, and release details.

Getting Started

Ways to Use

Use Modellix Agent Canvas in Coding Agents

What You Get

Requirements

Install

Host Compatibility

First Use and API Key

Typical Image Workflow

Useful MCP Tools

Project Data

Upgrade and Uninstall

Troubleshooting

Next Steps

Plugin

Skill

REST API

GitHub Repository

​What You Get

​Requirements

​Install

​Host Compatibility

​First Use and API Key

​Typical Image Workflow

​Useful MCP Tools

​Project Data

​Upgrade and Uninstall

​Troubleshooting

​Next Steps

Plugin

Skill

REST API

GitHub Repository

What You Get

Requirements

Install

Host Compatibility

First Use and API Key

Typical Image Workflow

Useful MCP Tools

Project Data

Upgrade and Uninstall

Troubleshooting

Next Steps