Using IconVectors with GitHub Copilot CLI

GitHub Copilot CLI can work on the icon that is already open in IconVectors on your Windows desktop. You register IconVectorsMcp.exe as a stdio MCP server, Copilot CLI launches it when a session needs it, and that sidecar forwards each call over loopback (127.0.0.1:61337 by default) to the running application. From there Copilot can read the active document and selection, create and edit geometry, render previews, export files, navigate Icon Explorer, and run the Explorer batch operations, all through the same live document model the desktop UI uses.

It is a different setup from the two other things called Copilot. Copilot Chat in VS Code is configured through .vscode/mcp.json and has its own guide. GitHub's cloud coding agent runs in a hosted environment where localhost is not your desktop, so it cannot reach this integration at all. This guide covers IconVectors 2.0+ on Windows; the macOS and Linux 2.00 builds are coming soon.

1. Start IconVectors

Launch the application the normal way and leave it running:

& 'C:\Program Files\Axialis\IconVectors\IconVectors.exe'

You don't start the MCP side yourself. IconVectorsMcp.exe sits beside IconVectors.exe in the install folder, and Copilot CLI launches it as a stdio process when it needs it; don't run it as a separate background service. If you installed to a custom location, check that the file is there, because its path goes into the config in the next step.

The sidecar reaches the application on 127.0.0.1:61337. If you changed Options/McpPort in IconVectors, use that port in the config instead. With two instances open, only the one that owns the configured port receives calls, and there is no instance selector, so either close the other one or give it a different port.

2. Register the server with copilot mcp add

Add a user-scoped server named iconvectors and expose every tool with --tools "*". Everything after the -- is the command line Copilot CLI will run, so the executable path is quoted and the port follows it:

copilot mcp add --tools "*" iconvectors -- "C:\Program Files\Axialis\IconVectors\IconVectorsMcp.exe" --port 61337
copilot mcp list
copilot mcp get iconvectors

Keep the name iconvectors. This guide assumes it, and under that name all 155 tools keep their raw names. Change the path if IconVectors lives somewhere other than C:\Program Files\Axialis\IconVectors, and the port if you changed McpPort.

The result lands in ~/.copilot/mcp-config.json, which on Windows is %USERPROFILE%\.copilot\mcp-config.json. If you'd rather write that file yourself, this is the shape:

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

A project can carry its own copy: .mcp.json in the checkout, or .github/mcp.json when the whole team should get it. Project servers require folder trust, so if a project-level iconvectors entry doesn't show up, check trust before you check the JSON. Copilot CLI does not read .vscode/mcp.json; a working VS Code setup does nothing for the CLI, so register the server here even if Copilot Chat already has it.

3. Verify the connection

copilot mcp list should show iconvectors, and copilot mcp get iconvectors should print back the command, args and tools filter you registered. Inside an interactive session the equivalents are slash commands:

• /mcp list
• /mcp show iconvectors
• /mcp reload, after a hand edit to the config or when discovery looks stale

Then have Copilot make the four discovery calls, in this order: app_ping, app_getInfo, app_getCapabilities and app_get_workspace. The ping proves the sidecar reached the application; the other three tell you which instance answered, what it can do, and whether the workspace is Editor or Explorer. One prompt covers all four:

• Use the iconvectors MCP server to call app_ping, app_getInfo, app_getCapabilities and app_get_workspace, then summarize what is open.

Before any change, have it inspect the state it is about to touch: document_getInfo and selection_get in Editor, explorer_get_state and explorer_list_entries in Explorer. Copilot CLI asks permission for each MCP call by default. Say yes to these; narrowing the prompts comes later.

4. Install the skill and keep instructions short

IconVectors 2.0+ ships an iconvectors-mcp skill: a SKILL.md with the inspect, mutate, recover and verify workflow, plus a references directory. Help -> Open MCP Files Folder opens the per-user MCP helper-files folder, which is the first place to look for it. Copy the whole iconvectors-mcp folder, references included, to one of these locations in your project:

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

Don't copy SKILL.md on its own; the skill expects its references directory next to it. Run /skills reload in the session, then /skills info iconvectors-mcp to confirm it loaded. When you need the exact arguments of a tool, the installed command reference and machine schema are the source, and the skill points at them.

Copilot CLI also reads AGENTS.md and the GitHub instruction files. Keep those short: always-on policy and a pointer to the skill. Task-specific expertise and the tool schemas belong in the skill, not pasted into every repository's instructions.

5. Make a first bounded edit

Run one small change end to end before you hand the setup real work. The sequence is the same in every client:

1. Inspect: capabilities, workspace, then the document and selection.
2. Make one bounded Editor mutation, something you can see on the canvas.
3. Reinspect the element you touched and the document.
4. Save or export only if you asked for it, and only to a native Windows path the desktop application can see.

Element ordinals are live document identities, not permanent IDs. Anything structural (create, delete, reparent, reorder, compound-path work, replacing the whole document) can make an ordinal you saw a moment ago stale, so reinspect after those instead of reusing the old target.

When a task needs several related edits, put them in one transaction. history_beginTransaction returns a txId; do the edits, then pass that exact ID to history_commitTransaction, or to history_rollbackTransaction if a step fails. Don't leave a transaction open or mix unrelated work into it. And know what sits outside document Undo entirely: document_new, document_open and document_setSvg replace the document and clear its Undo history; Save, Save As and export are not Undo operations; Explorer create, rename, delete, paste, duplicate, grouping and batch apply change files on disk. Explorer Paste and Duplicate offer a dry run, and every batch tool is plan then apply: review the summary, diagnostics and plan_id, then apply that unchanged plan. A rejected apply consumes the plan, so build a new one rather than retrying the old ID.

Working with 155 tools

Copilot CLI is naming-compatible with all 155 production IconVectors tools. With the server named iconvectors there is no sanitization, truncation, collision or client-specific rename, so a name in the command reference is the name you will see in the session.

A catalog that size still needs managing on the client. The tools list in the config takes "*" or selected raw tool names, so a project that only does Explorer batch work can register a smaller set. Per session, --available-tools and --excluded-tools narrow what the model sees without editing the config. Leave deferTools at its default, "auto", so Copilot loads definitions from a large catalog on demand; "never" keeps all definitions visible. /context shows how much of the window is in use, and /compact trims the history once a long session has built up.

Whatever you narrow to, keep application, capability, workspace and target-state discovery in the active set. And these are Copilot CLI controls: IconVectors 2.00 doesn't serve named or dynamic tool profiles, so there is nothing to switch on the server side.

Tool approval

By default Copilot CLI asks before every MCP invocation. You can pre-decide individual tools per session with the server(tool) form. This allows the read-only health check and blocks whole-document replacement:

copilot --allow-tool="iconvectors(app_ping)" --deny-tool="iconvectors(document_setSvg)"

Deny rules override allow rules. Keep the prompts for anything that writes: save and export, document replacement, Explorer file operations, and batch apply. Approving the whole server to make the prompts go away is the one shortcut we'd ask you not to take. Approval is a policy control; it isn't an Undo guarantee, and it doesn't change what IconVectors does with the call.

Troubleshooting

The server is absent

Run copilot mcp list and copilot mcp get iconvectors. Then check the scope you registered in (user or project), folder trust for a project server, that the command path is absolute and quoted, the port, and the tools filter.

Discovery looks stale

Run /mcp reload. GitHub documents a cache-disable setting; use it only if live discovery still lags after a reload.

The bridge is unavailable

The sidecar starts but calls fail. Start IconVectors, match port 61337 (or your McpPort value), and confirm with app_getInfo that you reached the intended application, workspace and document. The sidecar's send/receive timeout to the application is 10 seconds, separate from Copilot CLI's own startup and request timeouts, so an unresponsive application fails the call after that long.

You need logs

Copilot CLI writes under ~/.copilot/logs/, and /session reports the current log path. Start a session with --log-level=debug, or run /diagnose, for bounded troubleshooting. IconVectors doesn't publish a separate sidecar log file, so the client log is the place to look.

A path or an output fails

Use native absolute Windows paths: quoted in shell commands, backslashes doubled in JSON. A path that exists only in a sandbox, a container or WSL is not a desktop path. For big results, ask for bounded DOM, SVG, Explorer or preview output, and minified SVG, instead of a full document or a base64 PNG.

Copilot CLI versus the cloud coding agent

Copilot CLI runs on your machine, which is why it can launch IconVectorsMcp.exe and reach 127.0.0.1:61337. GitHub's Copilot cloud coding agent runs in a separate hosted environment. Its localhost is that environment, not your Windows desktop, so it cannot reach this integration, and adding MCP configuration on the cloud side isn't an alternate route to the live application. IconVectors doesn't publish a remote HTTP MCP endpoint.

For the current CLI commands and flags, see the official GitHub Copilot CLI MCP documentation.

If you don't have 2.00 installed yet, download the free 30-day trial of IconVectors for Windows and run the first bounded edit above.