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 (Apply Palette, Resize Icons, Apply Strokes) is a pair of tools: a plan tool and an apply tool. The plan parses and validates every target and returns a summary, diagnostics and a plan_id; nothing is written. 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.

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. 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. 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.00 trial for Windows, connect one client, and stop after the plan the first time.