MCP Integration

IconVectors 2.00 supports local automation through the Model Context Protocol (MCP). An MCP-capable coding client can inspect and control the running IconVectors desktop application: it can work with the active Editor document and selection, navigate Icon Explorer, create and edit SVG geometry, render previews, export files, and run the accepted Explorer Batch Starter operations.

The production IconVectors 2.00 server exposes 155 MCP tools. This page explains the shared connection and safety model. Use one of the client-specific setup guides for exact configuration.

How the local connection works

The Windows integration uses two cooperating processes:

  • IconVectors.exe is the desktop application. It owns the current workspace, document, selection, Undo history, Explorer state, rendering, and file operations.

  • IconVectorsMcp.exe is a local stdio sidecar launched by the MCP client. Do not run it as a separate background service.

  • The sidecar forwards calls to the already-running application over IPv4 loopback. The default endpoint is 127.0.0.1:61337.

Start IconVectors normally before connecting. If the application setting Options/McpPort was changed, pass the same port to the sidecar. When more than one IconVectors instance is open, only the instance that owns the configured port receives calls; there is no separate instance selector.

IconVectors does not publish a remote HTTP MCP endpoint. A cloud coding agent, hosted connector, container, or WSL process cannot reach the user’s desktop application merely by connecting to its own localhost.

Note

Client pages use C:\Program Files\Axialis\IconVectors as the normal installed-product example. Replace that path when IconVectors is installed elsewhere. Paths passed to tools must be native Windows paths visible to the desktop application, not paths that exist only in a client sandbox.

What the 155 tools cover

The catalog covers application and workspace discovery, document and selection state, SVG DOM inspection, creation, element and path editing, styles, gradients, palettes, icon operations, previews, export, history, preferences, and Icon Explorer file and batch operations.

The installed sidecar supplies its catalog through MCP tools/list. Public tool names use underscores, for example app_ping and document_getSvg. The eight supported clients in this documentation do not require IconVectors tool names to be rewritten. Use the installed command reference or machine schema when exact arguments are needed; this user guide does not duplicate all 155 definitions.

Discover, inspect, mutate, verify

Use the same sequence in every client:

  1. Call app_ping, app_getInfo, app_getCapabilities, and app_get_workspace.

  2. Inspect the intended workspace. In Editor, use document_getInfo and selection_get plus bounded DOM or style queries. In Explorer, use explorer_get_state and explorer_list_entries.

  3. Prepare the smallest valid operation. Confirm paths and destructive intent before replacement, Save As, export, delete, move, or multi-file changes.

  4. Perform one bounded mutation.

  5. Inspect the affected document, selection, element, Explorer generation, or output path again before continuing.

  6. Save or export only when requested.

Editor and Explorer are distinct states. Switch deliberately with app_set_workspace and inspect again. Explorer navigation that returns status: "accepted" has started asynchronously; poll explorer_get_state until the requested folder is the accepted current folder before issuing another navigation or file operation.

Element ordinals are live document identities rather than permanent IDs. Creation, deletion, reparenting, reordering, compound-path work, or whole document replacement can make a previously observed ordinal stale. Reinspect after structural edits instead of reusing old targets.

Undo, transactions, and filesystem changes

Many active-document mutations participate in IconVectors Undo/Redo. For several related document edits:

  1. Call history_beginTransaction and keep its returned txId.

  2. Perform only compatible active-document mutations.

  3. Pass that exact ID to history_commitTransaction. If a step fails, use history_rollbackTransaction instead.

Do not leave a transaction open or include unrelated work in it. Transactions and document Undo do not cover every operation:

  • document_new, document_open, and document_setSvg replace state and clear document Undo history.

  • Save, Save As, export, preferences, palette files, view state, and selection changes are not document Undo operations.

  • Explorer create, rename, delete, paste, duplicate, grouping, and batch apply change the filesystem and cannot be undone through document history.

Explorer Paste and Duplicate support dry run. Each Explorer Batch Starter tool uses a separate plan then apply protocol: review the summary, diagnostics, and returned plan_id, then apply only that unchanged current plan. A rejected apply consumes the plan; inspect current state and create a new plan rather than retrying the old ID.

Two current argument details

When these tools are useful in a workflow, use the accepted 2.00 behavior:

  • selection_selectAll.includeHidden omitted or set to true includes hidden selectable elements. Set it to false for visible-selection semantics.

  • document_placeFiles.position is an optional {x, y} top-left target in current SVG document coordinates. Omitting it keeps normal placement.

Consult the installed schema before calling either tool; these details are not substitutes for the full argument definition.

Working with a large catalog

Client limits and discovery features differ. IconVectors 2.00 does not serve named or dynamic tool profiles. Any allowlist, exclusion, deferred-schema setting, Tool Search feature, or tool picker described in a client guide is a client-side control.

Useful task-focused selections include:

  • application and state discovery plus Explorer tools,

  • application, document, selection, creation, style, element, history, and preview tools for basic editing,

  • inspection, selection, DOM, path, history, and preview tools for path work,

  • inspection plus code, render, and export tools for output,

  • application/workspace discovery plus Explorer tools for batch work.

Always keep application, capability, workspace, and target-state discovery in the active set. Prefer bounded DOM or Explorer queries and minified SVG when a full SVG, preview PNG, or base64 payload would create unnecessary output.

Skills and persistent instructions

The distributed iconvectors-mcp skill contains the shared inspect, mutation, recovery, and verification workflow. Copy the complete skill folder, including its references directory, to the location documented for the client. Do not copy only SKILL.md when its references are needed.

Use short persistent files such as AGENTS.md, CLAUDE.md, GEMINI.md, steering, or Copilot instructions only for always-on policy or a pointer to the skill. Do not paste the complete tool catalog into every repository instruction file.

Approval and safety

Begin with client approval prompts enabled. Review the exact tool and arguments for document replacement, save/export, Explorer filesystem operations, and batch apply. Client trust, allowlists, and auto-approval are policy controls; they are not an Undo guarantee and do not change IconVectors behavior.

If the intended document, selection, Explorer folder, destination, or IconVectors instance is uncertain, inspect or ask for the missing intent. Do not force document replacement, fabricate a selection, or globally approve disk-changing tools merely to suppress prompts.

Troubleshooting

Server not discovered

Check the client-specific configuration scope and syntax, the absolute path to IconVectorsMcp.exe, and the client’s server list or MCP panel. Let the client launch the sidecar.

Sidecar starts but calls fail

Start IconVectors, match the port, and check application responsiveness. The sidecar’s application-bridge send/receive timeout is 10 seconds, which is separate from a client’s sidecar startup or request timeout.

Wrong application, workspace, or selection

Use app_getInfo and state inspection. With several instances, assign distinct ports and verify identity before mutation.

Path fails

Use a native absolute Windows path. Quote executable paths in shell commands and escape backslashes in JSON. A client sandbox or cloud path is not a desktop path.

Explorer request appears stuck or stale

Wait for navigation to settle, reacquire Explorer state, and regenerate a batch plan if needed. Read structured status, category, and diagnostics rather than inferring success from prose.

Catalog or output is too large

Use the client-specific tool-selection feature and bounded results. Consult the client’s MCP log or output panel; IconVectors does not publish a separate sidecar log-file location.

Client setup guides

See Developer Features for non-MCP developer output features.