Skip to main content

Connecting AI agents

Ask Claude, 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.

Claude, Claude Code and VS Code connect by signing in to Moio (below). Codex, Cursor and other clients connect with an agent token (below).

One setup serves every document you open later; there is no per-document step. Editor tabs you already have open connect within a few seconds of the setup.

Connecting by signing in​

  1. In the dashboard, go to Settings → Agents.
  2. Connect your client:
    • Claude: press Set up Claude. Claude opens with Moio filled in; press Connect.
    • Claude Code: copy the command shown and run it in a terminal. Then run /mcp in Claude Code, choose moio and choose Authenticate.
    • VS Code: add the server URL shown as an MCP server. VS Code asks you to sign in when it starts the server.
  3. Sign in to Moio if asked, and Allow the agent to work in Moio for you.
  4. Ask your agent to work in your open Moio document, for example "In my open Moio document, build a pricing card".

Connected agents under Settings → Agents lists each agent you connected this way, with when you connected it and when it last worked. Disconnect → Confirm Disconnect cuts it off within about a minute; to use it again, connect it again.

Connecting with an agent token​

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

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.
  • Agent tokens lists each token's label, when it was created and when an agent last used it.

Connecting your client​

These setups use an agent token; Claude, Claude Code and VS Code can connect by signing in instead (above). 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 --scope user --transport http moio "<server URL>" --header "Authorization: Bearer <token>"

--scope user makes Moio available in every folder you start Claude Code in.

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>. A client that signs in to MCP servers through OAuth can connect without a token only if Moio has registered it; today that is Claude, Claude Code and VS Code.

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, or disconnect it, 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 already open connects a few seconds after your first token or sign-in; if it still doesn't, reload it.
  • 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.
  • Claude Code still uses an old token after you set up a new one: an earlier setup made without --scope user takes precedence in the folder where it was made. Run claude mcp remove moio --scope local in that folder.
  • 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.