Using IconVectors with Codex CLI

Asking Codex CLI to write SVG by hand gets you markup that never touches your document. Register the IconVectors MCP helper as a Codex server and your prompts run against the live editor instead: Codex calls tools that inspect, draw, edit, render and export on the icon that is open, and in 2.0+ it can also browse the Icon Explorer and run the batch tools.

This guide is written for IconVectors 2.0+ on Windows, where the helper is C:\Program Files\Axialis\IconVectors\IconVectorsMcp.exe and the catalog is exactly 155 tools. The macOS and Linux builds of 2.00 are coming soon. The current 1.70 builds ship the same helper at /Applications/IconVectors.app/Contents/MacOS/IconVectorsMcp and /usr/bin/IconVectorsMcp, and the configuration below works there too, without the Explorer and batch tools until 2.00 reaches those platforms.

Before you begin

• Start IconVectors before you launch Codex, and leave it running.
• Windows: confirm that IconVectorsMcp.exe sits beside IconVectors.exe. Use native Windows Codex; a Codex running in WSL or a container cannot see the desktop process or its paths.
• macOS and Linux (1.70): confirm the helper exists at the path above.
• The helper talks to the application on 127.0.0.1:61337. If you changed Options/McpPort in IconVectors, use that port everywhere below.

1. Start the editor

Windows (2.0+)

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

macOS (1.70)

open -a /Applications/IconVectors.app

Linux (1.70)

/usr/bin/IconVectors

Codex launches the helper as its own stdio process; do not start IconVectorsMcp yourself. With several IconVectors windows open, only the instance that owns the configured port answers, and there is no instance picker, so keep one window open while you set things up.

2. Configure Codex CLI

Codex reads MCP servers from config.toml: %USERPROFILE%\.codex\config.toml for your user account, or .codex/config.toml inside a trusted project. Name the server iconvectors.

Windows example

[mcp_servers.iconvectors]
command = 'C:\Program Files\Axialis\IconVectors\IconVectorsMcp.exe'
args = ['--port', '61337']
cwd = 'C:\Program Files\Axialis\IconVectors'
startup_timeout_sec = 20
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"

The two timeouts give the helper time to start and give long calls such as export time to finish. default_tools_approval_mode = "prompt" makes Codex ask before every IconVectors call; the approvals section below explains why that stays on for a while. Change the path if IconVectors is installed elsewhere and the port if you changed Options/McpPort.

macOS example (1.70 helper)

[mcp_servers.iconvectors]
command = '/Applications/IconVectors.app/Contents/MacOS/IconVectorsMcp'
args = ['--port', '61337']
cwd = '/Applications/IconVectors.app/Contents/MacOS'
startup_timeout_sec = 20
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"

Linux example (1.70 helper)

[mcp_servers.iconvectors]
command = '/usr/bin/IconVectorsMcp'
args = ['--port', '61337']
startup_timeout_sec = 20
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"

If you prefer the command line, codex mcp add iconvectors -- "C:\Program Files\Axialis\IconVectors\IconVectorsMcp.exe" --port 61337 writes the same server entry; add the timeouts and the approval mode in the file afterwards. Start a new Codex session after changing the configuration.

3. Verify the connection

From PowerShell, list the configured servers:

codex mcp list

Inside a Codex session, /mcp shows the active server and its tools. Then ask for the four discovery calls, in this order:

• Use the iconvectors server to call app_ping and tell me whether IconVectors answered.
• Call app_getInfo and summarize the running instance.
• Call app_getCapabilities and list what this build supports.
• Call app_get_workspace and tell me whether the Editor or the Explorer is active.

Check the version, workspace and current document in the answers before you ask for a change. They tell you which IconVectors instance Codex reached, which matters as soon as you have two open.

4. Install the skill and AGENTS.md

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

• project: .agents/skills/iconvectors-mcp/SKILL.md
• user: %USERPROFILE%\.agents\skills\iconvectors-mcp\SKILL.md

For always-on instructions, copy codex-AGENTS.md.template from the same folder to the root of your repository as AGENTS.md. User-level instructions live in %USERPROFILE%\.codex\AGENTS.md, and nested AGENTS.md files can refine them per folder. Keep those files short: policy and a pointer to the skill. The workflow and the tool schemas stay in the skill, not pasted into every repository.

5. Make a first bounded edit

Run one small change through the whole loop before you give Codex real work:

1. Ask Codex to call document_getInfo and selection_get and describe what it sees. If no document is open, ask explicitly for a new 32 x 32 document.
2. Ask for one shape, or one bounded change to the selected element.
3. Have it inspect the created element and the document again and compare with what you asked for.
4. Save or export only if you asked for it, and only to a destination you named.

For several related edits, have Codex open a history transaction with history_beginTransaction, keep the returned txId, make the edits, then commit or roll back with that exact ID. Save, export, document replacement and Explorer file changes sit outside transactions and outside document Undo, which is why they stay behind approval prompts.

Once the loop works, try the complete example in Create an Info Icon with Codex CLI; it uses the exact prompt from the IconVectors MCP documentation and shows the result as a video.

Working with 155 tools

Codex discovers the complete catalog of 155 tools under their canonical underscore names, with no client-specific renaming and no documented per-server ceiling. For a narrower task, set enabled_tools or disabled_tools on the server entry to expose a subset. Keep the discovery tools (app_ping, app_getInfo, app_getCapabilities, app_get_workspace) and the inspection tools for the state you are editing in every subset. This filtering is a Codex setting; IconVectors serves the same catalog to every client and has no profiles of its own.

Prefer bounded DOM and Explorer queries, and document_getSvg with svg_minified, over a full SVG, a preview PNG or a base64 payload when the smaller answer would do.

Approvals

Keep default_tools_approval_mode at prompt while you evaluate the integration, or write narrower per-tool policies. The calls to keep reading before they run are the ones Undo does not cover: document replacement, Save As and export, Explorer create, delete, move, paste and duplicate, and batch apply. Inspect, mutate, verify. A Codex approval policy changes what Codex asks you; it does not change what IconVectors does with the call, and it is not an Undo.

Troubleshooting

The server is absent

Run codex mcp list. Check the TOML table name ([mcp_servers.iconvectors]), which config.toml you edited, the full executable path, and whether the project is trusted when you used the project file. Start a new session after the fix.

The helper starts but calls fail

Start IconVectors and match the port. If another IconVectors instance claimed the port, close it or give it a different Options/McpPort. The helper's own send and receive timeout to the application is 10 seconds, separate from the Codex startup and tool timeouts in the config.

Wrong document, workspace or selection

Reinspect with app_get_workspace, document_getInfo, selection_get or explorer_get_state. Do not let Codex guess a recovery mutation or replace a document it does not know.

A Windows path fails

Use a path the desktop application can see. Quote paths with spaces in shell commands; escape backslashes in JSON arguments.

Too many tools, or too much output

Select a task-focused subset and ask for bounded results. Do not auto-approve filesystem mutations globally to get out of an approval loop.

Codex versus hosted OpenAI services

This setup is for Codex running on the same Windows machine as IconVectors. ChatGPT connectors and the OpenAI API use remote HTTP MCP connections; they cannot launch or reach the local stdio helper, and IconVectors publishes no remote endpoint. For the current Codex configuration keys, see the official Codex MCP documentation.

If IconVectors is not installed yet, download the free trial and work through the five steps with a real icon open.