Using IconVectors with Cursor

Overview

Cursor can launch the IconVectors 2.00 sidecar as a local stdio MCP server on Windows. The sidecar forwards calls over loopback to the already-running IconVectors application, giving Cursor access to the active Editor document, Icon Explorer, preview/export, history, and Batch Starter operations.

See MCP Integration for the shared connection, state, transaction, and safety model.

Prerequisites

  • Start IconVectors 2.00 normally.

  • Confirm IconVectorsMcp.exe exists beside IconVectors.exe.

  • The default bridge is 127.0.0.1:61337. Match a custom Options/McpPort value if necessary.

Configure Cursor MCP

Create .cursor/mcp.json for a project or %USERPROFILE%\.cursor\mcp.json for user scope:

{
  "mcpServers": {
    "iconvectors": {
      "type": "stdio",
      "command": "C:\\Program Files\\Axialis\\IconVectors\\IconVectorsMcp.exe",
      "args": ["--port", "61337"]
    }
  }
}

The command is the normal installed-product example. Replace the path or port when your installation differs. It is a JSON string, not a shell fragment; do not wrap it in an extra command shell.

Open Cursor Settings ‣ Tools & MCP (shown as Customize ‣ MCPs in some Cursor surfaces), enable the iconvectors server, and approve its tools as appropriate. Reload the Cursor window after configuration changes only when needed.

Verify the connection

Use the Tools & MCP view to confirm that the server is enabled and that tools were discovered. Ask Cursor to call:

  • app_ping

  • app_getInfo

  • app_getCapabilities

  • app_get_workspace

Then inspect document_getInfo and selection_get in Editor, or explorer_get_state in Explorer. Do not begin verification with Save As or export.

Install instructions and the IconVectors skill

Copy cursor-agent-instructions.template.md to the project root as AGENTS.md, or merge its short policy into an existing root or nested AGENTS.md.

Cursor Rules use .cursor/rules/*.mdc files with valid rule frontmatter. Simply renaming a plain Markdown template to .mdc is not sufficient.

Install the complete distributed iconvectors-mcp skill, including its references directory, at either:

  • .agents/skills/iconvectors-mcp/SKILL.md

  • .cursor/skills/iconvectors-mcp/SKILL.md

User equivalents under the corresponding home-directory folders are also supported. Keep the tool schema in the shared references rather than copying it into every rule.

First workflow

Try one small inspected change:

  1. Inspect the current workspace, document, selection, and relevant DOM/style state.

  2. Create one simple shape or change one current element.

  3. Reinspect the result and render a preview only if visual verification is useful.

  4. Save or export only when a destination was explicitly requested.

Use a history transaction for several compatible active-document edits. An allowlist does not make Save As, export, replacement, or Explorer filesystem operations Undoable.

Working with 155 tools

Cursor is naming-compatible with 155/155 production IconVectors tools. The canonical underscore names work without client-specific renaming.

Cursor publishes no fixed MCP tool-count or output ceiling. Task-focused exposure can still improve selection: keep discovery tools and enable the Editor, Explorer, Path, Paint, Export, or Batch families needed for the task. These are client-side choices; IconVectors does not dynamically serve named profiles.

Cursor 3.6 and later can review tool calls automatically and use allowlists. Prefer bounded DOM and Explorer results and avoid full preview/base64 output unless it is needed.

Approval and safety

Cursor asks for tool approval by default. Auto-review and allowlists should cover only understood, bounded calls. Continue prompting for:

  • document replacement,

  • save and export,

  • Explorer file operations,

  • batch apply.

An allowlist is a client policy, not an Undo guarantee. Reinspect the target after structural edits because element ordinals can become stale.

Troubleshooting

Server is missing or disabled

Validate JSON and scope, then inspect Tools & MCP. Reload the window if the client has not picked up a saved configuration change.

Executable or bridge fails

Verify the absolute Windows path, start IconVectors, and match the port. With several IconVectors instances, confirm identity and state because the protocol has no instance selector.

Logs are needed

Open View ‣ Output (Ctrl+Shift+U) and choose MCP Logs.

Wrong state or stale navigation

Reinspect workspace, document, selection, or Explorer state. Wait for asynchronous Explorer navigation to settle before another operation.

Path, catalog, or output fails

Use a native absolute Windows path with JSON escaping. Expose a task-focused subset and request bounded results.

A call times out

Distinguish Cursor startup from the sidecar’s 10-second application-bridge I/O timeout. Check MCP Logs and application responsiveness first.

For current client controls, see the official Cursor MCP documentation.