Using IconVectors with VS Code / GitHub Copilot

This page explains the recommended local setup for Visual Studio Code with GitHub Copilot. Windows and Linux can both use this workflow.

Overview

IconVectors includes a desktop editor (IconVectors on Linux, IconVectors.exe on Windows) and a companion MCP server (IconVectorsMcp on Linux, IconVectorsMcp.exe on Windows).

For Visual Studio Code and GitHub Copilot, the recommended setup is:

  1. Start IconVectors yourself on Linux, or IconVectors.exe on Windows, so the local bridge is available.

  2. Let Visual Studio Code launch IconVectorsMcp on Linux, or IconVectorsMcp.exe on Windows, as the MCP server process.

That avoids double-starting the sidecar and keeps the responsibilities clear:

  • IconVectors / IconVectors.exe = the editor and local bridge

  • IconVectorsMcp / IconVectorsMcp.exe = the MCP server

See also MCP Integration.

Prerequisites

Before you configure the integration, make sure you have:

  • access to GitHub Copilot,

  • Visual Studio Code 1.99 or later,

  • on Linux:

    • IconVectors and IconVectorsMcp in /usr/bin,

    • iconvectors-mcp-tools.json in ~/.local/share/Axialis/IconVectors/MCP,

  • on Windows:

    • IconVectors.exe and IconVectorsMcp.exe in C:\Program Files\Axialis\IconVectors,

    • iconvectors-mcp-tools.json in %APPDATA%\Axialis\IconVectors\MCP.

If you are part of an organization or enterprise with Copilot Business or Copilot Enterprise, MCP access may also be controlled by policy in your Copilot environment.

Keeping iconvectors-mcp-tools.json in the per-user MCP folder is a better fit than putting it beside the executables. VS Code and Copilot do not import that file directly; they connect to the live MCP server process instead.

You can open that folder directly from IconVectors with Help ‣ Open MCP Files Folder.

If your installation includes the optional MCP helper files, the most useful Copilot files are:

  • %APPDATA%\Axialis\IconVectors\MCP\vscode-copilot-implementation-instructions.md

  • %APPDATA%\Axialis\IconVectors\MCP\iconvectors-mcp-command-reference.md

  • %APPDATA%\Axialis\IconVectors\MCP\vscode-copilot-AGENTS.md.template

On Linux, the same files are typically in:

  • ~/.local/share/Axialis/IconVectors/MCP/vscode-copilot-implementation-instructions.md

  • ~/.local/share/Axialis/IconVectors/MCP/iconvectors-mcp-command-reference.md

  • ~/.local/share/Axialis/IconVectors/MCP/vscode-copilot-AGENTS.md.template

Use them like this:

  • open vscode-copilot-implementation-instructions.md and copy the MCP server block into mcp.json,

  • keep iconvectors-mcp-command-reference.md in the workspace if you want extra tool context,

  • copy vscode-copilot-AGENTS.md.template to AGENTS.md in the repository root if you want Copilot Agent mode to prefer IconVectors for icon tasks.

VS Code / Copilot works best with AGENTS.md for this scenario. A generic SKILL.md is not the main end-user instruction format here.

How the connection works

IconVectors currently works like this:

  • IconVectors / IconVectors.exe starts the local IconVectors bridge.

  • IconVectorsMcp / IconVectorsMcp.exe is the MCP sidecar.

  • The default bridge port is 61337, unless you override it.

  • The sidecar is launched with IconVectorsMcp --port <port> on Linux, or IconVectorsMcp.exe --port <port> on Windows.

For VS Code and GitHub Copilot, the recommended model is:

  1. Start IconVectors manually on Linux, or IconVectors.exe on Windows.

  2. Let VS Code launch IconVectorsMcp through the MCP configuration.

Start IconVectors

Start the editor first:

Windows:

.\IconVectors.exe

Linux:

/usr/bin/IconVectors

Do not use --mcp for the normal VS Code / Copilot workflow, because VS Code should be the process that launches IconVectorsMcp / IconVectorsMcp.exe.

Use --mcp only for standalone testing outside VS Code.

Create the MCP configuration

The recommended repository-local configuration file is:

.vscode/mcp.json

Add this content:

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

On Linux, use:

{
  "servers": {
    "iconvectors": {
      "type": "stdio",
      "command": "/usr/bin/IconVectorsMcp",
      "args": ["--port", "61337"]
    }
  }
}

Replace the path with your actual install folder.

If your IconVectors bridge uses another port because of ICONVECTORS_MCP_PORT or application configuration, replace 61337 with the same value here.

Note

VS Code also supports storing MCP configuration in your user-profile mcp.json. Use MCP: Open User Configuration from the Command Palette if you want the server available across workspaces.

Optional Windows wrapper

If you want to make the working folder explicit, you can launch through cmd.exe:

{
  "servers": {
    "iconvectors": {
      "type": "stdio",
      "command": "cmd",
      "args": [
        "/c",
        "cd /d \"C:\\Program Files\\Axialis\\IconVectors\" && IconVectorsMcp.exe --port 61337"
      ]
    }
  }
}

Use this wrapper only if you need it. The direct executable form is cleaner.

Start the MCP server in VS Code

After saving .vscode/mcp.json:

  1. Open the file in VS Code.

  2. Start the configured server from the CodeLens at the top of the server list, or use MCP: List Servers from the Command Palette and start it there.

  3. If prompted, confirm that you trust the server configuration.

Open Copilot Chat and use the tools

Once the server is running:

  1. Open Copilot Chat in Visual Studio Code.

  2. Switch the chat mode to Agent.

  3. Click the tools icon to inspect the available MCP servers and tool list.

At that point, the iconvectors server should be visible to Copilot.

Verify that the server is working

Start with simple health checks.

Suggested prompts:

  • Use the IconVectors MCP server to call app_ping.

  • Use IconVectors and call app_getInfo.

  • Create a new 32x32 document named test icon, use the current palette, and then call document_getInfo.

These are good first-run validation calls because they confirm that:

  • the MCP sidecar launched correctly,

  • the sidecar can reach the running editor,

  • document commands are usable end-to-end.

Try a real editing task

Once the connection works, try a small drawing task.

Example prompt:

Use IconVectors to create a new 32x32 icon named blue-circle, draw a centered blue circle, then export it as SVG to C:\Temp\blue-circle.svg.

On Linux, a matching path example would be:

Use IconVectors to create a new 32x32 icon named blue-circle, draw a centered blue circle, then export it as SVG to /tmp/blue-circle.svg.

That flow maps naturally to the IconVectors MCP tool surface, including document_new, create_ellipse, style-editing commands, and export commands.

Suggested AGENTS.md instructions

If you want Copilot to prefer IconVectors whenever a task involves icons or SVG editing, start from the installed template:

  • %APPDATA%\Axialis\IconVectors\MCP\vscode-copilot-AGENTS.md.template

On Linux, the matching template path is:

  • ~/.local/share/Axialis/IconVectors/MCP/vscode-copilot-AGENTS.md.template

Copy it to the repository root as AGENTS.md.

Example:

# AGENTS.md

Use the IconVectors MCP server whenever the task involves creating, drawing, inspecting, editing, recoloring, rendering, or exporting SVG vector icons through the live IconVectors document.

Decision rules:

- If the user asks to open a file and modify it, open or edit that file. Do not create a new document unless the user explicitly asks for one.
- If the user asks to draw something and a document is already open, draw inside the current icon unless the user explicitly wants a separate icon.
- If no icon is open and the user asks to draw something without specifying a size, create a new 32x32 px icon.
- If the prompt starts with "make" or "create", assume the user wants a new icon from scratch unless the prompt explicitly says to modify an existing or open file. Default size: 32x32 px if none is specified.

Workflow rules:

- Inspect first with `app_ping`, `app_getInfo`, `document_getInfo`, `selection_get`, and DOM/style tools before large edits.
- Prefer IconVectors MCP tools over manual SVG text editing when the task is primarily visual, geometric, or export-oriented.
- Preserve the existing layer, group, and palette structure unless the user asks to reorganize it.
- If no output format is specified, default to SVG.

Drawing and UI-icon rules:

- Aim for pixel-perfect application UI icons: simple silhouettes, minimal detail, consistent optical weight, balanced negative space, and clean alignment.
- Prefer whole-pixel coordinates for filled geometry.
- For 1px strokes, use half-pixel positioning when needed for crisp rasterization.
- Avoid details, gaps, or overlaps thinner than 1px unless explicitly requested.
- Use consistent corner radii, spacing, and visual rhythm across the icon.

Color and style rules:

- If no color palette is specified, use the current active palette.
- Prefer palette colors only; map named colors to the visually closest palette swatch.
- If the prompt specifies an exact HTML hex color such as `#4DA3FF`, use that exact color.
- If the prompt specifies `currentColor`, use the literal `currentColor` value.
- If no color is specified, use the currently selected fill and stroke colors.
- If no stroke is requested, use fill only.
- If the user asks for a line-style icon, use stroke only and no fill.
- If stroke is requested and no width is specified, use a 1px stroke.
- Unless the user specifies otherwise, use round line caps and round line joins.
- If the user asks for a single-color gradient such as "blue gradient", choose the closest palette blue and create a vertical linear gradient with the top stop 20% lighter and the bottom stop 20% darker.
- If multiple gradient colors are specified, use those colors, preferring palette matches unless exact hex colors or `currentColor` are requested.

Exports:

- Default to `SVG` when no output format is specified.

Troubleshooting

Copilot does not see the server

Check these points:

  • IconVectors.exe is already running.

  • The path to IconVectorsMcp.exe is correct.

  • The port in mcp.json matches the bridge port used by IconVectors.

  • The server is actually started in VS Code.

  • Copilot Chat is in Agent mode.

The server starts but calls fail

This usually means the sidecar is running but cannot reach the editor bridge.

Check that:

  • IconVectors is already open.

  • The bridge port is correct.

  • A firewall or endpoint security product is not blocking local loopback communication.

You launched IconVectors.exe --mcp

That may start a second MCP sidecar while VS Code is also trying to launch one. For normal Copilot usage, start only IconVectors.exe and let VS Code launch IconVectorsMcp.exe.

About the JSON manifest

iconvectors-mcp-tools.json is useful for documentation, diagnostics, testing, and version matching, but it is not the file VS Code reads to connect to the MCP server. VS Code connects using the command and args declared in mcp.json. The live server then exposes the tools described by the manifest.