Using IconVectors with Codex / OpenAI

This page explains the recommended local setup for Codex and related OpenAI tooling that can launch MCP servers on the same machine.

Overview

IconVectors uses two cooperating processes:

  • the desktop editor, which owns the document, user interface, undo stack, rendering state, and local bridge,

  • the MCP helper, which speaks stdio MCP and forwards tool calls to the running editor.

For Codex, the recommended model is:

  1. Start IconVectors yourself.

  2. Let Codex launch the local MCP helper.

  3. Keep the helper port aligned with the IconVectors bridge port.

See also MCP Integration.

Before you begin

Make sure these files are available for your platform.

Windows

Application files:

  • C:\Program Files\Axialis\IconVectors\IconVectors.exe

  • C:\Program Files\Axialis\IconVectors\IconVectorsMcp.exe

Optional helper files:

  • %APPDATA%\Axialis\IconVectors\MCP\iconvectors-mcp-tools.json

  • %APPDATA%\Axialis\IconVectors\MCP\iconvectors-mcp-command-reference.md

  • %APPDATA%\Axialis\IconVectors\MCP\codex-AGENTS.md.template

  • %APPDATA%\Axialis\IconVectors\MCP\iconvectors-codex-skill\SKILL.md

macOS

Application bundle:

  • /Applications/IconVectors.app

Executables inside the bundle:

  • /Applications/IconVectors.app/Contents/MacOS/IconVectors

  • /Applications/IconVectors.app/Contents/MacOS/IconVectorsMcp

Optional helper files:

  • ~/Library/Application Support/Axialis/IconVectors/MCP/iconvectors-mcp-tools.json

  • ~/Library/Application Support/Axialis/IconVectors/MCP/iconvectors-mcp-command-reference.md

  • ~/Library/Application Support/Axialis/IconVectors/MCP/codex-AGENTS.md.template

  • ~/Library/Application Support/Axialis/IconVectors/MCP/iconvectors-codex-skill/SKILL.md

You can open the helper-files folder directly from IconVectors with Help ‣ Open MCP Files Folder.

Start IconVectors

Start the editor first, then leave it running while Codex launches the MCP helper.

Windows:

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

macOS:

open /Applications/IconVectors.app

Do not normally start the editor with --mcp when using Codex. In the normal Codex workflow, Codex should be the process that launches the MCP helper.

Configure Codex

Codex stores MCP configuration in config.toml. The standard locations are:

  • user configuration: ~/.codex/config.toml

  • project configuration: .codex/config.toml

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

macOS example

[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

Replace the paths if IconVectors is installed elsewhere. If you changed the default bridge port through ICONVECTORS_MCP_PORT or application settings, use the same port here.

Optional CLI registration

Instead of editing config.toml manually, you can register the server from the command line.

Windows:

codex mcp add iconvectors -- "C:\Program Files\Axialis\IconVectors\IconVectorsMcp.exe" --port 61337

macOS:

codex mcp add iconvectors -- /Applications/IconVectors.app/Contents/MacOS/IconVectorsMcp --port 61337

Use codex mcp list to confirm that the server is registered.

Verify the connection

A good first-run check is:

  1. Start IconVectors.

  2. Start Codex.

  3. Confirm that the iconvectors server appears in the active MCP server list.

  4. Ask Codex to call lightweight health-check tools first.

Good first prompts:

  • Use the IconVectors MCP server to call app.ping and report whether the editor is connected.

  • Use IconVectors to call app.getInfo and summarize the current application state.

  • Create a new 32x32 document named "test icon", draw a centered circle using the current palette, and export it as SVG.

Optional: use AGENTS.md

If you want Codex to prefer IconVectors for icon work, start from the installed template:

  • Windows: %APPDATA%\Axialis\IconVectors\MCP\codex-AGENTS.md.template

  • macOS: ~/Library/Application Support/Axialis/IconVectors/MCP/codex-AGENTS.md.template

Copy it to either:

  • your repository root as AGENTS.md

  • your Codex profile as ~/.codex/AGENTS.md

Optional: install the Codex skill

If you want stronger IconVectors-specific behavior, copy the installed skill folder into your Codex skills directory as ~/.codex/skills/iconvectors-mcp.

Source folders:

  • Windows: %APPDATA%\Axialis\IconVectors\MCP\iconvectors-codex-skill

  • macOS: ~/Library/Application Support/Axialis/IconVectors/MCP/iconvectors-codex-skill

The resulting file should be:

  • ~/.codex/skills/iconvectors-mcp/SKILL.md

Troubleshooting

If Codex cannot connect:

  • make sure IconVectors is already running,

  • make sure the port in Codex matches the bridge port used by IconVectors,

  • make sure the helper exists at the configured path,

  • make sure the command and cwd values in config.toml point to the real install location,

  • on Windows, prefer a native Windows Codex session over WSL for the simplest setup,

  • on macOS, if you installed the app outside /Applications, update the bundle path accordingly,

  • on macOS, confirm that the helper exists at IconVectors.app/Contents/MacOS/IconVectorsMcp,

  • on macOS, if Gatekeeper or signing policies block launch, reinstall a properly signed copy of the app.

Hosted OpenAI note

The current IconVectors MCP design is a local stdio server. That is a good fit for local tools such as Codex running on the same machine. Hosted web/API connectors typically expect a public HTTP MCP endpoint instead, so they require an HTTP wrapper or relay service in front of the local IconVectors bridge.