Drive Icon Explorer and Batches from MCP

An agent that only sees SVG text can rewrite one icon at a time, and it never sees the folder the icon lives in. IconVectors 2.0+ puts the Icon Explorer and the batch tools on the MCP surface, so the same coding agent that edits your code can open a folder of icons, list what is there, plan a batch across the selection, and apply it, all through the running desktop application.

This guide assumes a client is already connected (step 1 links the setup guides) and walks through one folder job end to end, as prompts you type. It applies to IconVectors 2.0+ on Windows. The tool names below are the documented ones. The Explorer file tools and the batch tools have their own names and arguments, which you take from the client's tools/list output or from the command reference and machine schema installed with the application, so the prompts describe what to do rather than pretending to know every name.

1. Connect and discover

Any of the eight documented clients works: Codex CLI, Claude, Cursor, VS Code Copilot, Gemini CLI, Kiro, Cline or GitHub Copilot CLI. Start IconVectors, check that the client lists the iconvectors server, then open with the four discovery calls:

Call app_ping, app_getInfo, app_getCapabilities and app_get_workspace on the iconvectors server, then tell me which IconVectors instance answered and whether it is in the Editor or the Explorer.

app_getInfo matters more than it looks. Only the IconVectors instance that owns the configured port answers, and there is no instance picker, so this is how you confirm you are talking to the window you think you are.

2. Switch to the Explorer and open a folder

Editor and Explorer are separate states, and the agent has to change state on purpose. app_set_workspace switches. The Explorer open-folder tool then takes a native Windows path, C:\Projects\app\icons and not a path inside the agent's sandbox or WSL, because the path has to make sense to the desktop application.

Switch IconVectors to the Explorer workspace with app_set_workspace, then open C:\Projects\app\icons with the Explorer open-folder tool. Poll explorer_get_state until it reports that folder as the current one, and tell me when it does. Do nothing else until then.

That last line is not decoration. Explorer navigation is asynchronous: a request that comes back with status: "accepted" has started, not finished. The agent should poll explorer_get_state until the folder it asked for is the accepted current folder, and only then issue the next navigation or file operation. Firing the next call early gets a stale answer or a rejection.

3. List and choose the icons

Call explorer_list_entries and give me the SVG filenames in that folder, one per line, with their canvas sizes. Leave out the subfolders and do not open anything.

Ask for bounded output. A folder listing is small; a full SVG, a preview PNG or a base64 payload is not, and most clients start truncating or warning long before the context is gone. Once you can see the names, describe the selection in words the agent can turn into arguments: "the eight files whose names start with nav-", not "those ones".

Two file tools support a dry run, Paste and Duplicate. When you want copies of a set in the same folder, a dry run tells you what names the duplicates would get (name-copy.svg, then name-copy-2.svg) before anything is written.

4. Copy the set into a working folder first

Explorer create, rename, delete, paste, duplicate, grouping and batch apply all change the filesystem, and none of them can be undone through document history. So have the agent put the selection in a fresh child folder first, with the grouping tool, and run the batch on the copies.

Group the eight nav-*.svg files into a new child folder called nav-recolor, copying them, not moving them. Then navigate into nav-recolor, wait for explorer_get_state to confirm it, and list what is there.

Your client will ask you to approve the grouping call. Read the arguments before you say yes: the folder name, the copy-or-move flag, and the list of files. That ten-second check is the whole reason to keep approvals on.

5. Plan the batch and read the plan

Each batch operation is a pair of requests on one tool, mode: "plan" and mode: "apply". The plan parses and validates every target and returns a summary, diagnostics and a plan_id; nothing is written. Since 2.10 all 14 Explorer commands are there, named after the menu: explorer_batch_apply_palette, explorer_batch_replace_colors, explorer_batch_convert_to_current_color, explorer_batch_adjust_colors, explorer_batch_auto_gradient, explorer_batch_resize_icons, explorer_batch_center_fit, explorer_batch_rotate_flip, explorer_batch_apply_strokes, explorer_batch_outline_strokes, explorer_batch_optimize_svg_files, explorer_batch_overlay_icons, explorer_batch_make_icon_versions and explorer_batch_export_icons. Batch Rename is the one Explorer batch that stays GUI-only. Read the summary yourself: how many files change, how many stay unchanged, how many are unsupported or failed, and what the diagnostics say about the odd ones.

Select all SVG files in nav-recolor and create an Apply Palette plan for them with the current palette. Show me the plan summary, the diagnostics and the plan_id, then stop. Do not apply.

If the counts look wrong, change the selection or the settings and ask for a new plan. Do not let the agent "fix" a plan by editing it: a plan is applied unchanged or not at all. And if the document open in the Editor is one of the targets, the plan will say so; close that document and plan again.

For a sense of what the agent sends, here is the Replace Colors plan request for the Explorer selection, turning the old brand red into the new blue on fills and strokes. A target of "fill" or "stroke" narrows it, and explicit paths can replace use_explorer_selection when the agent is working from a file list rather than from what you clicked:

{
  "mode": "plan",
  "use_explorer_selection": true,
  "source_color": "#FF0000",
  "replacement_color": "#2468AC",
  "target": "both"
}

The reply carries the changed and unchanged counts, per-file diagnostics and the plan_id. The apply request is just {"mode": "apply", "plan_id": "..."} with that id. The output batches (overlays, icon versions, bitmap export) take the same shape plus their output folder and suffix options, and the plan lists every destination so the agent can show you the filenames before it writes them.

6. Apply and verify

Apply the plan with that exact plan_id. Then call explorer_get_state, list the entries again, and open nav-home.svg in the Editor with document_open so I can look at it.

Two rules about apply. It accepts only the current, unchanged plan, so a plan made against a folder that changed since is refused. And a rejected apply consumes the plan: the agent has to inspect the folder and build a new plan, not retry the old id. A correct response carries a structured status, category and diagnostics; read those rather than the agent's prose summary, because "done" in prose is not verification.

Approve the document_open call knowingly. It replaces whatever is open in the Editor and clears that document's Undo history, which is fine here and not fine in the middle of an unsaved edit.

Keeping the agent safe

Keep the client's approval prompts on for anything that touches disk or replaces a document: document_setSvg, document_open, save and export, every Explorer file operation, and batch apply. Approve per call, or per tool where the client allows it. A blanket approval for the whole server is the one shortcut to avoid, because approval is a client policy and not an undo.

When the agent is unsure which folder, selection or instance it is looking at, the right move is to inspect again or ask you, never to guess a recovery or force a document replacement. The sidecar's bridge to the application has a 10-second send and receive timeout, separate from the client's own timeouts, so a call that hangs usually means IconVectors is busy or not running. In 2.10 app_ping reports the requested and the actual port, which settles the other common cause: a configured port that was busy, with the companion falling back to a loopback port. A tool list alone proves nothing about the bridge; app_ping does. And when an element id is not unique, the agent now gets an ambiguous_element_id error with the candidates instead of a silent pick. After any structural edit in the Editor, element ordinals can go stale; the agent should reinspect before reusing one. The iconvectors-mcp skill that ships with 2.0+ encodes all of this, and the 2.10 edition knows the 14 batch tools. Install it where your client looks for skills and the agent follows the sequence on its own.

Try the whole loop on a copy of a small folder: download the IconVectors 2.10 trial for Windows, connect one client, and stop after the plan the first time.