Using IconVectors with Kiro

Kiro can edit the icon that's open in IconVectors instead of an SVG you paste into the chat. Kiro IDE and Kiro CLI both launch IconVectorsMcp.exe as a local stdio MCP server, and that process forwards every call over loopback to the IconVectors application that's already running, so the agent reads the real document, selection and Icon Explorer folder and changes them in place, previews and exports included.

This guide is for IconVectors 2.0+ on Windows. The macOS and Linux builds of 2.00 are coming soon. It covers the mcp.json entry, how to confirm that all 155 tools came through, where the skill goes, and two Kiro-specific settings to decide on early: Tool Search, which is CLI only and off by default, and approvals.

1. Start IconVectors

Start the application the way you normally do and leave it running. Kiro only ever launches the sidecar; it never starts IconVectors for you, and a sidecar with no application behind it fails on the first call. From PowerShell:

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

While you're in that folder, check that IconVectorsMcp.exe sits next to IconVectors.exe. The application listens on 127.0.0.1:61337 by default. If you've changed Options/McpPort, keep the new value handy, because the same port goes into Kiro's config in the next step. With two instances open, only the one that owns the configured port receives calls; there's no instance picker, so close the other instance or give it a different port.

2. Add the server to Kiro's MCP configuration

Kiro looks for MCP servers in two files, and that's true of both the IDE and the CLI:

• .kiro/settings/mcp.json in the workspace
• %USERPROFILE%\.kiro\settings\mcp.json for your user account

If the same server name appears in both, the workspace entry wins. Put this in whichever file fits how you work:

{
  "mcpServers": {
    "iconvectors": {
      "command": "C:\\Program Files\\Axialis\\IconVectors\\IconVectorsMcp.exe",
      "args": ["--port", "61337"],
      "disabled": false,
      "autoApprove": [],
      "disabledTools": []
    }
  }
}

The command is the normal install path; change it if IconVectors is somewhere else, and change the port if you changed Options/McpPort. The doubled backslashes are JSON escaping, not a typo. Keep the server name as iconvectors; the naming check described in the next step was run under that name.

The other three keys aren't boilerplate. disabled has to be false or the server never loads. autoApprove stays empty on purpose; there's a section on it below. disabledTools is where you'd list tools you want hidden from the agent, and for now it stays empty too. You don't need to restart anything: saving the file makes Kiro reconnect.

3. Verify the connection

In Kiro IDE, open the Kiro panel and switch to its MCP servers view, which shows each server's status and the tools it exposed. In Kiro CLI, /mcp lists the connected servers and /tools lists the tools available from them. Outside a chat session, the same check from PowerShell is:

kiro-cli mcp list

With the server named iconvectors, Kiro accepts all 155 tools as shipped: no invalid names, no empty descriptions, no truncations, no collisions. If a tool you expect is missing, look on the Kiro side (a validation message or a disabledTools entry) rather than at the catalog.

Then make the four discovery calls before anything else. Prompts along these lines work:

• Call app_ping on the iconvectors server and tell me whether the editor answered.
• Call app_getInfo and app_getCapabilities and summarize what came back.
• Call app_get_workspace, then describe the current document and selection, or the current Explorer folder, without changing anything.

What comes back tells you which IconVectors instance you're talking to and whether Kiro is looking at the Editor or at Icon Explorer. Those are separate states. The agent switches between them with app_set_workspace and should inspect again after switching, because every edit that follows depends on the selection and element ordinals being what it thinks they are.

4. Install the skill and point steering at it

The iconvectors-mcp skill ships with IconVectors 2.0+. It holds the inspect, mutate, recover and verify workflow the agent should follow, with the detail split out into a references directory. Help -> Open MCP Files Folder opens the per-user MCP helper-files folder, the first place to look for it. Kiro doesn't document .agents/skills as a skill root, so the folder goes here instead:

.kiro/skills/iconvectors-mcp/SKILL.md

Copy the complete folder, references included. SKILL.md on its own isn't the skill.

Steering only needs a pointer. A couple of lines in a root AGENTS.md, or in a file under .kiro/steering/, telling the agent to read the skill before it touches IconVectors is enough. If you define a custom agent, include the skill in it explicitly and set includeMcpJson: true so the agent also loads the servers from mcp.json. Don't paste the 155-tool catalog into steering. The sidecar publishes it through tools/list on every connection, and the command reference is there when you need exact arguments.

5. Make a first bounded edit

Keep the first job small enough that you can watch the whole loop. The skill teaches one sequence; walk through it once so you know what a good run looks like:

1. Inspect the workspace, the document, the selection, and whatever DOM or style state the change depends on.
2. Create one simple element, or change one thing about the selected element.
3. Reinspect the result. Check the geometry, or render a preview when the numbers aren't enough.
4. Save or export only if you asked for it, and only to a native Windows path you named.

A prompt that fits: Inspect the current document and selection first. Then change only the fill of the selected element to #2563eb, reinspect it, and report what changed. Don't save.

When a task needs several related document edits, have the agent wrap them in a history transaction: history_beginTransaction returns a txId, the edits follow, and history_commitTransaction gets that exact ID back (or history_rollbackTransaction if a step fails). Don't leave a transaction open, and don't mix unrelated work into it. Transactions and document Undo also have limits you should know before the first save. document_new, document_open and document_setSvg replace the document and clear its Undo history. Save, Save As and export aren't Undo operations. Explorer changes (create, rename, delete, paste, duplicate, grouping, batch apply) go to the filesystem and can't be undone from document history at all.

Two more things to know. Element ordinals are live positions, not permanent IDs, so after a create, delete, reorder, reparent or compound-path change the agent should reinspect rather than reuse an ordinal it saw earlier. And when the job is about files rather than the open document, the agent switches to Explorer with app_set_workspace, reads explorer_get_state and explorer_list_entries, and treats a navigation that returns status: "accepted" as started rather than done: it polls explorer_get_state until the requested folder is current before issuing another file operation. The Explorer batch tools are plan-then-apply. Review the summary, the diagnostics and the returned plan_id, apply only that unchanged plan, and if the apply is rejected, build a new plan instead of retrying the old ID.

Tool Search in Kiro CLI

155 tools is a lot of schema to put in front of a model on every request. Kiro CLI's answer is Tool Search: it indexes the MCP tools, gives the model a compact list, and loads a tool's full schema only when the model asks for it. Two catches. It's off by default, and it exists only in the CLI.

Turn it on with:

kiro-cli settings toolSearch.enabled true

Even when enabled, the defaults only activate it once MCP schemas exceed 5 percent of the context or 50,000 tokens. If you'd rather it load on demand whenever any MCP tools are present, zero both thresholds:

kiro-cli settings toolSearch.minPct 0
kiro-cli settings toolSearch.minTokens 0

/tools reports token use alongside the tool list, so you can compare before and after. When the model searches, it shows up in the session as a read-only tool_search call.

Kiro IDE doesn't have Tool Search for now. If catalog size becomes a problem there, the options are blunter: list what you don't need in disabledTools, or set "disabled": true on the server and flip it back to false for icon work. Whatever you trim, keep app_ping, app_getInfo, app_getCapabilities, app_get_workspace and the inspection tools for the state you're editing; the skill's workflow starts with them.

One thing to be clear about: Tool Search and disabledTools are Kiro features. IconVectors 2.00 serves the same 155 tools to every client and has no tool profiles of its own.

Approvals and disabledTools

Kiro asks before it runs an MCP tool, and the config above leaves autoApprove empty so it keeps asking. Leave it that way for the first sessions. The calls you want to read before they run are the ones document Undo doesn't cover: save and export, whole-document replacement (document_new, document_open, document_setSvg), any Explorer filesystem change, and a batch apply.

The tempting shortcut is "autoApprove": ["*"]. It approves every tool on the server, including all of the above, and it's the wrong setting for this server. If the prompts get in the way, approve specific tools instead. Copy each name exactly as the Kiro surface you're using displays it rather than typing it from memory.

disabledTools is a different lever. It takes raw server tool names and removes them from the agent entirely, so it shrinks what the model can see; it doesn't grant or deny anything the model can still see. And an approval, however you configure it, is a Kiro policy. It isn't an Undo guarantee, and it doesn't change what IconVectors does once the call arrives.

Troubleshooting

The server is missing

Validate the JSON, the path to IconVectorsMcp.exe, the scope (workspace file or user file), "disabled": false, and the port. Then reconnect from the MCP servers view in the IDE, or check /mcp in the CLI.

A tool is excluded

Read Kiro's MCP validation message and check disabledTools. The shipped catalog passes Kiro's current naming rules for all 155 names and descriptions, so an excluded tool points at configuration, not at the server.

The bridge fails

The sidecar started but couldn't reach the application. Make sure IconVectors is running and that the port in args matches the editor (61337 unless you changed Options/McpPort), then call app_getInfo and check the workspace state. The bridge's send and receive timeout is 10 seconds, which is separate from any startup or request timeout Kiro applies to the sidecar itself.

You need logs

In Kiro IDE, open Output and pick Kiro - MCP Logs. In Kiro CLI, /logdump --mcp includes the MCP diagnostics. Read the dump before you share it.

The catalog or a path fails

For catalog size in the CLI, enable Tool Search and confirm it with /tools. For paths, use native absolute Windows paths and escape the backslashes in JSON. A path that exists only inside a client sandbox, a container or WSL isn't a path the desktop application can open.

For current client behavior, which changes more often than this page does, see the official Kiro MCP documentation.

If you don't have 2.00 installed yet, download the IconVectors free trial for Windows and run the loop above with Kiro.