Skip to main content

Connecting AI agents

Ask Claude Code, Codex, Cursor or VS Code with GitHub Copilot to build and edit designs in the Moio document you have open. The agent works in your own editor tab: you watch its changes appear, collaborators receive them as your edits, and Ctrl + Z undoes them like your own. Moio connects to these tools as an MCP server.

Looking for generated text inside the editor instead? See AI content generation.

Setting up​

You need one of the clients above, or any other MCP client (other clients), and a document open in the Moio editor in a browser tab signed in as you.

  1. In the dashboard, go to Settings → Agents, enter a label such as the machine the agent runs on, and press Create Token.
  2. Choose your client's tab. It shows a command or configuration with the token filled in; copy it and follow the steps for your client (below). The token is shown only this once: copy what you need before you press Done.
  3. Open the document in the editor and wait for it to load. If the editor was already open when you created your first token, reload it.
  4. Start your agent and ask it to work in your open Moio document, for example "In my open Moio document, build a pricing card".

One setup serves every document you open later; there is no per-document step.

About agent tokens​

  • A token lets whoever holds it act as you in every document you have open. Keep it private, and revoke it if it leaks.
  • Tokens don't expire. Revoke → Confirm Revoke cuts the agent off within about a minute.
  • Your tokens lists each token's label, when it was created and when an agent last used it.

Connecting your client​

The dashboard supplies the full server URL and token in each setup snippet. In the examples below, replace <server URL> with that URL (including /mcp) and <token> with your agent token.

Keep configurations containing your token in your personal settings. If you already have MCP servers configured, add the moio entry alongside them instead of replacing the file.

Claude Code​

Run the copied command in a terminal, then restart Claude Code:

claude mcp add --transport http moio "<server URL>" --header "Authorization: Bearer <token>"

Codex​

Add this section to ~/.codex/config.toml (the .codex folder in your home directory), then restart Codex:

[mcp_servers.moio]
url = "<server URL>"
http_headers = { Authorization = "Bearer <token>" }

See the Codex MCP configuration reference for more options, including reading the bearer token from an environment variable.

Cursor​

Add a moio entry to ~/.cursor/mcp.json (the .cursor folder in your home directory):

{
    "mcpServers": {
        "moio": {
            "url": "<server URL>",
            "headers": { "Authorization": "Bearer <token>" }
        }
    }
}

Enable the moio server in Cursor's MCP settings and use Agent chat. See Cursor's MCP documentation.

VS Code with GitHub Copilot​

Run MCP: Open User Configuration from VS Code's Command Palette and add a moio entry to servers:

{
    "servers": {
        "moio": {
            "type": "http",
            "url": "<server URL>",
            "headers": { "Authorization": "Bearer <token>" }
        }
    }
}

Run MCP: List Servers, select moio, and start it. Use Agent mode in Copilot Chat with Moio's tools enabled. See VS Code's MCP setup guide.

Other clients​

Any MCP client that supports Streamable HTTP transport and a custom Authorization header works. The Other clients tab on the token page shows the server URL and the raw token; set the header to Bearer <token>. Moio uses agent tokens; browser sign-in through OAuth is not supported.

Working with several documents open​

The agent reaches only the editor tabs you have open, signed in as you. It can't open a document or reach one you haven't opened.

  • With one tab open, the agent works there. With several, it asks which document you mean, or picks the one you named, and keeps working in that tab until you tell it otherwise.
  • If you close that tab or open another document in it, the agent's calls fail. Ask it to choose again.
  • Every answer names the document it worked in.
  • You can keep editing while the agent works, and you can drive it from another window; the editor tab keeps working in the background.
  • The agent can read what you have selected: select layers and refer to "the selection" in your request.

What an agent can do​

In short: what you can do in that document with the mouse and the properties panel, except undo. In a document you can only view, or one opened in Read only mode, it can read and export but not edit (who can do what).

  • Reading: the pages, the active page and your selection, any layer with its children, an outline of a page or layer, search by name or type, screenshots and SVG exports of layers, a component set with each state resolved to CSS-like values, the fonts available in the editor, and every property the properties panel offers, with whether a value has any effect on a given layer.
  • Layers: create frames, rectangles, ellipses, lines, polygons, stars and text; move, resize, rotate, scale, reorder, duplicate, delete; wrap layers in a frame and unwrap them; move layers into other frames and onto other pages; crop frames; boolean operations, flatten and outline stroke.
  • Styling: everything the properties panel sets: fills and strokes, including gradients and images; effects; corner radius, opacity, blend mode, visibility, constraints, min/max size; text content, font, size, spacing, alignment and decoration, for a whole text or for part of it, links included.
  • Layout: turn on or adjust Flex and Grid layout, including direction, gap, padding, alignment, wrapping and grid tracks, and how each layer in a layout sizes and places itself: Fill, Hug, auto margins, grid cells.
  • Pages: add, duplicate and reorder pages, and delete any but the one you're on.
  • Components: turn layers into components and component sets, create variants, make interactive components with their states and transitions, add and bind component inputs, fill slots, and place, swap, reset and detach instances. Deleted components can be restored.
  • Variables and interactions: create, change and delete variables, bind properties and component inputs to them, and add events and actions as the prototyping panel does.
  • Images and SVG: import image and SVG files the agent provides. An agent that can run commands, such as Claude Code, uploads a file from your computer straight to Moio instead of copying its content into its reply, which is much faster for large files. The editor never downloads from a web address on the agent's behalf.
  • Scripts: send many changes as one script (below).

How agent edits behave​

  • Undo. Agent edits go into the undo history of the tab it works in, alongside yours. Ctrl + Z there undoes the latest step, whoever made it. The agent itself can't undo; it fixes mistakes with further edits or asks you to undo. Undo history lives in the tab, so another tab can't undo the agent's edits, and reloading the tab empties it (undo in a shared document).
  • Your view stays yours. Edits leave your selection, the current page and your scroll and zoom alone. Layers the agent creates aren't selected, and it changes the selection only when asked to. Imported images and SVGs go where the agent places them, or in the middle of your view.
  • Duplicate and delete work like yours. A duplicated component becomes an instance of it, and a duplicated variant becomes a new variant of its set. A layer deleted inside an instance is hidden rather than removed, and deleted components keep working in their instances.
  • Your typing stays yours. While you edit a text or the points of a vector, the agent doesn't change that text's content or styles or those points; it tries again once you're done. Moving or deleting the layer ends your editing, as a collaborator's would.
  • Offline. While the editor is disconnected from the server, or still catching up after reconnecting, edits are refused and reads still work (connection loss).
  • Review the result. Text in a shared document could be written to mislead an agent. Layer names and text are handed to the agent as design content, never as instructions, but review what it did, as you would with a collaborator's edits.

Seeing what the agent is doing​

As soon as it starts on a request, the agent names what it's working on. The editor shows a notification at the bottom of the canvas, marked Agent, with a spinner while the agent is busy and a second line for the current step, such as "Writing a script for the card grid" or "Drawing trees". Only you see it; collaborators don't. While the agent is busy, the title of the browser tab starts with ⏳, so you can tell from your other tabs whether it's still working.

View on the notification takes you to the agent's recent work: it opens the page the agent last worked on and zooms to fit the layers the agent recently created or changed there, outlining them for a moment. Your selection stays as it is.

An agent that hasn't done anything for 2 minutes shows as possibly stopped. Dismiss hides the notification; the agent can still continue.

Stopping an agent​

  1. Stop on the notification asks you to confirm: Yes stops the agent from making further changes for this request and tells it to check with you before going on; No lets the agent carry on. Stopping can't interrupt an edit or a script that is already running.
  2. Stopping doesn't undo anything; use Ctrl + Z for that.
  3. An agent could start new work on its own. To cut it off for good, revoke its token under Settings → Agents.

Scripts​

For larger changes the agent may send a script instead of many single edits. What you'll notice:

  • A whole script is one undo step.
  • The editor pauses while a script runs: normally up to 2 seconds, at most 10. This is expected.
  • When a script fails partway, the changes it made before the failure stay in the document. One Ctrl + Z removes them.

Troubleshooting​

  • The agent says there is no live editor session: open the document in the editor and wait for it to load. A tab that was open before you created your first token needs a reload.
  • The agent says its token is invalid or revoked: the token was revoked, or the client setup contains a typo. Create a new token and redo your client's setup; a token can't be shown again.
  • The agent's calls fail after you closed the tab or opened another document in it: ask the agent to choose the document again.
  • The agent reports a timeout: the edit may still have been applied. Check the document, then ask the agent to continue.
  • After a Moio update, the agent reports an unknown operation or a parameter it can't use: reload the editor tab, then restart your agent or reconnect its Moio MCP server to refresh the tools.
  • Edits are refused but reading works: the document is view-only for you, it's open in Read only mode, or the editor is reconnecting.