Using IconVectors with Codex / OpenAI

Overview

Codex can use IconVectors 2.00 as a local MCP server on Windows. Codex launches IconVectorsMcp.exe over stdio; the sidecar forwards calls over loopback to the already-running IconVectors desktop application.

This provides live access to Editor and Icon Explorer state, SVG editing, preview and export, Undo/Redo, and the accepted Explorer Batch Starter operations. See MCP Integration for the shared 155-tool contract and safety model.

Prerequisites

  • Start IconVectors 2.00 normally and leave it running.

  • Confirm IconVectorsMcp.exe is beside IconVectors.exe.

  • Use native Windows Codex for the simplest access to the Windows desktop process and paths.

  • The default bridge is 127.0.0.1:61337. Match a custom Options/McpPort value if one is configured.

Configure Codex MCP

Use %USERPROFILE%\.codex\config.toml for user scope. A trusted project can instead use .codex/config.toml.

[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"

C:\Program Files\Axialis\IconVectors is the normal installed-product example. Replace it and the port when your installation differs. Do not start the sidecar separately; Codex owns its stdio process.

Verify the connection

List configured servers from PowerShell:

codex mcp list

In a Codex session, use /mcp to inspect the active server and tools. Then ask Codex to call, in order:

  • app_ping

  • app_getInfo

  • app_getCapabilities

  • app_get_workspace

Confirm that the returned application version, workspace, and current document belong to the intended IconVectors instance before making changes.

Install the IconVectors skill and instructions

Copy the complete distributed iconvectors-mcp skill folder, including its references directory, to one of these locations:

  • project: .agents/skills/iconvectors-mcp/SKILL.md

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

For lightweight persistent instructions, copy codex-AGENTS.md.template to the repository root as AGENTS.md. User instructions can live in %USERPROFILE%\.codex\AGENTS.md; project and nested AGENTS.md files can refine them. Keep the complete workflow and schemas in the skill instead of pasting them into AGENTS.md.

First workflow

After discovery, try a small inspected edit:

  1. Ask Codex to inspect document_getInfo and selection_get. If no document is open, explicitly request a new 32 x 32 document.

  2. Create one simple shape or make one bounded change.

  3. Ask Codex to inspect the created element and document again.

  4. Save or export only if you requested a destination.

For several related document edits, ask Codex to use history_beginTransaction and commit or roll back the exact returned txId. Save, export, document replacement, and Explorer filesystem changes are outside document transactions and Undo.

Working with 155 tools

Codex can discover the complete production catalog of 155 tools. The canonical underscore names are supported without client-specific renaming, and Codex documents no fixed per-server tool-count ceiling.

For a narrower task, use the Codex server entry’s enabled_tools or disabled_tools setting to expose a client-side subset. Keep application, capability, workspace, and target-state discovery available. This filtering does not change IconVectors or select a server-side profile.

Prefer bounded DOM and Explorer queries or document_getSvg with svg_minified when a full SVG, preview, or base64 result would be excessive.

Approval and safety

Keep default_tools_approval_mode at prompt while evaluating the integration, or define narrower per-tool policies. Continue prompting for:

  • document replacement,

  • Save As and export,

  • Explorer file creation, deletion, move, paste, or duplicate,

  • Explorer batch apply.

Follow inspect, mutate, then verify. A Codex approval policy is not an IconVectors Undo guarantee.

Troubleshooting

Server is absent

Run codex mcp list and check the TOML table name, scope, full executable path, and trusted-project status. Start a new Codex session after changing configuration when needed.

Sidecar starts but calls fail

Start IconVectors and match the configured port. Check that another IconVectors instance did not claim the port. The sidecar’s 10-second application-bridge I/O timeout is separate from Codex startup and tool timeouts.

Wrong document, workspace, or selection

Reinspect with app_get_workspace, document_getInfo, selection_get, or explorer_get_state. Do not guess a recovery mutation or force replacement of an unknown dirty document.

Windows path fails

Use a path visible to the desktop application. Quote paths with spaces in shell commands; in JSON arguments, escape backslashes.

Too many tools or too much output

Select a task-focused client subset and request bounded results. Do not globally auto-approve filesystem mutations to resolve an approval loop.

Codex versus hosted OpenAI services

This setup is for Codex running on the same Windows machine. ChatGPT connectors and the OpenAI API use remote HTTP MCP connections; they cannot directly launch or reach this local desktop stdio sidecar.

For current Codex configuration details, see the official Codex MCP documentation.