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 includes a desktop editor (IconVectors on Linux, IconVectors.exe on Windows) and a companion MCP server (IconVectorsMcp on Linux, IconVectorsMcp.exe on Windows). For Codex, the recommended setup is:

  1. Start IconVectors so the application opens and its local bridge is available.

  2. Let Codex launch IconVectorsMcp as the MCP server process.

This keeps the GUI application and the MCP server in their intended roles:

  • IconVectors / IconVectors.exe = the editor

  • IconVectorsMcp / IconVectorsMcp.exe = the MCP server Codex talks to

See also MCP Integration.

Before you begin

Make sure these files are available.

On Linux, a packaged install typically uses:

  • application files in /usr/bin:

    • IconVectors

    • IconVectorsMcp

  • helper files in ~/.local/share/Axialis/IconVectors/MCP:

    • iconvectors-mcp-tools.json

On Windows, the typical layout remains:

  • application files in C:\Program Files\Axialis\IconVectors:

    • IconVectors.exe

    • IconVectorsMcp.exe

  • helper files in %APPDATA%\Axialis\IconVectors\MCP:

    • iconvectors-mcp-tools.json

Keeping iconvectors-mcp-tools.json in the per-user MCP folder is a better fit than putting it beside the executables. It stays version-matched with the installed build, but it remains easy for the user to inspect, copy, or override without needing administrator rights.

You can open that folder directly from IconVectors with Help ‣ Open MCP Files Folder.

If your installation includes the optional MCP helper files, the most useful Codex files are:

  • codex-implementation-instructions.md

  • iconvectors-mcp-command-reference.md

  • codex-AGENTS.md.template

  • iconvectors-codex-skill\SKILL.md

Use them like this:

  • open codex-implementation-instructions.md and copy the MCP configuration block into Codex,

  • keep iconvectors-mcp-command-reference.md in your repository or attach it if you want extra tool context,

  • copy codex-AGENTS.md.template to AGENTS.md in your project root or to ~/.codex/AGENTS.md if you want Codex to prefer IconVectors for icon tasks,

  • install iconvectors-codex-skill\SKILL.md into ~/.codex/skills/iconvectors-mcp if you want Codex to use a stronger reusable IconVectors workflow automatically.

By default, IconVectors uses port 61337. If you override the port through ICONVECTORS_MCP_PORT or the application configuration, use the same port everywhere below.

Start IconVectors

Start the editor first:

Linux package install:
/usr/bin/IconVectors

Windows install folder:
.\IconVectors.exe

Do not normally start it with --mcp when using Codex, because Codex is expected to launch the MCP server process itself.

Use this only for manual standalone testing outside Codex:

Linux:
/usr/bin/IconVectors --mcp

Windows:
.\IconVectors.exe --mcp

Configure Codex

Add an IconVectors MCP entry to one of these files:

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

  • project configuration: .codex/config.toml

Linux example:

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

Linux users can also register the server directly from Codex CLI:

codex mcp add iconvectors -- /usr/bin/IconVectorsMcp --port 61337

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

Replace the path with your actual install directory or build output.

Why this configuration works

  • command launches the IconVectors MCP server directly.

  • args passes the port used by the IconVectors local bridge.

  • cwd is useful on Windows installs, but not required for the packaged Linux layout.

  • The slightly longer timeouts help if the editor is still starting.

Restart Codex

After editing config.toml, start a new Codex session. If the MCP server is configured correctly, Codex should automatically load it when the session starts.

Verify the connection

A quick verification flow:

  1. Start IconVectors.

  2. Start Codex.

  3. In the Codex UI, check the active MCP servers.

  4. Ask Codex to test the connection.

Example 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", use the current palette, draw a centered circle, and export it as SVG.

Optional: help Codex choose IconVectors automatically

You can either write your own AGENTS.md file, or start from the installed template:

  • codex-AGENTS.md.template

Copy that file to your repository root as AGENTS.md, or to ~/.codex/AGENTS.md:

# AGENTS.md

Use the IconVectors MCP server whenever the task involves creating, editing, inspecting, rendering, or exporting SVG icons.

Prefer IconVectors tools over manual SVG text editing when the task is primarily visual or icon-design related.

This makes Codex more likely to use the IconVectors tools without being told each time.

Optional: install the Codex skill

For heavier IconVectors use, Codex can also use a dedicated skill pack.

Start from the installed folder:

  • iconvectors-codex-skill

Copy that folder to:

  • ~/.codex/skills/iconvectors-mcp

The resulting file should be:

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

For your reference, here is the contents of the SKILL.md file:

---
name: iconvectors-mcp
description: Use this skill when the user wants Codex to create, draw, inspect, edit, recolor, transform, render, or export SVG vector icons through the live IconVectors document.
---

# IconVectors MCP

Use this skill only when Codex has access to the IconVectors MCP server and the user wants work performed on the current drawing inside IconVectors.

## Scope

Use IconVectors MCP for:

- creating a new icon or document
- drawing shapes, paths, text, gradients, and groups
- editing the current icon geometry, styles, layers, palettes, and exports
- generating code targets such as SVG, Minified SVG, SVG Symbol, XAML, WPF Geometry, VectorDrawable, SwiftUI, VueTS, ReactTS, and C++
- producing previews and bitmap exports from the live drawing

Do not use this skill for:

- patching application source code
- editing files on disk when the user actually wants the current drawing changed in IconVectors
- speculative operations when the MCP server is unavailable

## Intent and document selection rules

- If the user asks to open a file and modify it, open or edit that file. Do not create a new document unless the user explicitly asks for a new icon.
- If the user asks to draw something and a document is already open, draw inside the current icon unless the user explicitly asks for a separate icon.
- If no icon is open and the user asks to draw something without specifying a size, create a new 32x32 px icon.
- If the prompt starts with "make" or "create", assume the user wants a new icon from scratch unless the prompt explicitly says to modify an existing or open file. Default size: 32x32 px if none is specified.
- If no output format is specified, default to SVG.

## Working style

- Inspect first, then edit.
- Prefer the smallest command set that solves the task.
- When several edits belong together, wrap them in a history transaction so the result is undoable as one step.
- Preserve the user's existing layer structure, naming, and palette unless the request says otherwise.
- If the user asks for a visual result but does not specify exact geometry, infer a reasonable icon design and keep it simple, readable, and production-oriented.

## UI-icon drawing rules

- Aim for pixel-perfect application UI icons: simple silhouettes, minimal detail, consistent optical weight, balanced negative space, and clean alignment.
- Prefer whole-pixel coordinates for filled geometry.
- For 1px strokes, use half-pixel positioning when needed for crisp rasterization.
- Avoid details, gaps, or overlaps thinner than 1px unless explicitly requested.
- Use consistent corner radii, spacing, and visual rhythm across the icon.
- Keep the design readable at small sizes and verify with the preview when practical.

## Color and style rules

- If no color palette is specified, use the current active palette.
- Prefer palette colors only; map named colors to the visually closest palette swatch.
- If the prompt specifies an exact HTML hex color such as `#4DA3FF`, use that exact color.
- If the prompt specifies `currentColor`, use the literal `currentColor` value.
- If no color is specified, use the currently selected fill and stroke colors.
- If no stroke is requested, use fill only.
- If the user asks for a line-style icon, use stroke only and no fill.
- If stroke is requested and no width is specified, use a 1px stroke.
- Unless the user specifies otherwise, use round line caps and round line joins.
- If the user asks for a single-color gradient such as "blue gradient", choose the closest palette blue and create a vertical linear gradient with the top stop 20% lighter and the bottom stop 20% darker.
- If multiple gradient colors are specified, use those colors, preferring palette matches unless exact hex colors or `currentColor` are requested.

## Default workflow

1. Inspect the current state.

- Start with `app_getInfo` and `document_getInfo`.
- If selection matters, check `selection_get`.
- If structure matters, use `dom_getSubtree`, `dom_getElement`, or `dom_query`.
- If appearance matters, inspect `style_get`, `gradient_list`, or `palette_getActive`.

2. Decide whether to create, edit, or export.

- New drawing: `document_new`, then `create.*`, `style.*`, `gradient.*`.
- Existing drawing edits: `selection.*`, `element.*`, `path.*`, `style.*`, `dom.*`.
- Whole-icon operations: `icon.*`.
- Palette work: `palette.*`.
- Export/code output: `export`, `export_toBitmap`, or `code_get`.

3. Group related edits.

- Use `history_beginTransaction` before multi-step edits.
- Commit with `history_commitTransaction`.
- If a step fails or the geometry becomes invalid, roll back with `history_rollbackTransaction`.

4. Verify the result.

- Re-read the affected state with `document_getInfo`, `selection_get`, `style_get`, `dom_getSubtree`, or `render_previewPng`.
- If the user asked for code output, call the requested export/code command explicitly instead of describing it from memory.

## Command families

### Document

- `document_new`, `document_open`, `document_getInfo`, `document_getSvg`, `document_setSvg`, `document_save`, `document_saveAs`

### Creation

- `create_group`, `create_rect`, `create_ellipse`, `create_line`, `create_path`, `create_polyline`, `create_polygon`, `create_textAsPaths`

### Selection and DOM

- `selection_get`, `selection_set`, `selection_selectAll`
- `dom_getElement`, `dom_getSubtree`, `dom_query`, `dom_setAttributes`, `dom_setStyle`, `dom_reorder`, `dom_reparent`, `dom_deleteElement`

### Element transforms

- `element_move`, `element_rotate`, `element_scale`, `element_reflect`, `element_matrix`, `element_duplicate`
- `element_alignHorizontalLeft`, `element_alignHorizontalCenter`, `element_alignVerticalCenter`
- `element_center`, `element_centerHorizontally`, `element_centerVertically`
- `element_distributeHorizontally`, `element_group`, `element_ungroup`, `element_delete`

### Path editing

- `path_convertToPath`, `path_getEditable`, `path_setEditable`
- `path_moveAnchor`, `path_moveHandle`, `path_insertAnchorAt`, `path_deleteAnchor`
- `path_setAnchorType`, `path_roundCorner`, `path_offset`, `path_outlineStroke`, `path_simplify`
- `path_booleanUnion`, `path_booleanSubtract`, `path_booleanIntersect`, `path_booleanExclude`
- `path_makeCompound`, `path_releaseCompound`

### Styling and gradients

- `style_get`, `style_setFill`, `style_setStroke`, `style_setStrokeWidth`, `style_setLineCap`, `style_setLineJoin`, `style_setOpacity`
- `gradient_createLinear`, `gradient_createRadial`, `gradient_list`, `gradient_get`, `gradient_addStop`, `gradient_updateStop`, `gradient_removeStop`, `gradient_setAngle`, `gradient_apply`, `gradient_applyToElement`

### Palette and recolor

- `palette_list`, `palette_getActive`, `palette_setActive`, `palette_addColor`, `palette_removeColor`, `palette_import`, `palette_export`
- `palette_addAllIconColors`, `icon_addAllColorsToPalette`, `icon_recolorWithPalette`

### Whole-icon operations

- `icon_resize`, `icon_resizeCanvas`
- `icon_colors_brightnessContrast`, `icon_colors_hueSaturation`, `icon_colors_levels`, `icon_colors_desaturate`, `icon_colors_invert`
- `icon_variants_makeHotVersion`, `icon_variants_makeDisabledVersion`, `icon_variants_makeDarkThemeVersion`
- `icon_badge_add`, `icon_badge_cutout`, `icon_badge_shadow`

### Rendering and export

- `render_previewPng`
- `export`
- `export_toBitmap`
- `code_get`

## References

- Command overview: `../iconvectors-mcp-command-reference.md`
- Tool schema: `../iconvectors-mcp-tools.json`
- Codex setup instructions: `../codex-implementation-instructions.md`
- Optional repository instructions: `../codex-AGENTS.md.template`

This is useful when you want Codex to apply richer IconVectors defaults automatically, including:

  • choosing whether to edit the current document or create a new one,

  • defaulting to a new 32x32 icon when no size is specified,

  • preferring the current palette and closest palette colors,

  • keeping icons pixel-perfect and SVG-first unless another output format is requested.

Troubleshooting

Codex cannot connect to IconVectors

Check these items:

  • IconVectors is running on Linux, or IconVectors.exe on Windows.

  • The port in Codex matches the port used by IconVectors.

  • IconVectorsMcp or IconVectorsMcp.exe exists at the configured path.

  • The install path in config.toml is correct.

  • The path is written as a valid TOML string.

Tip: on Windows, use either single-quoted strings with backslashes or forward slashes such as C:/Program Files/Axialis/IconVectors/IconVectorsMcp.exe.

I launched IconVectors --mcp (or IconVectors.exe --mcp) and Codex also starts the MCP server

That is usually unnecessary. For normal Codex use, start IconVectors normally and let Codex own the MCP server process.

I am using the Codex IDE extension on Windows

If your Codex setup runs through WSL, a Windows-only .exe integration may be less straightforward than using the native Codex app or a native Windows CLI session. For the simplest IconVectors setup, use Codex directly on Windows.

Important note about ChatGPT / OpenAI API

The current design is a good fit for Codex running on the same machine. It is not the same thing as a ChatGPT connector or a remote MCP server for the OpenAI API.

ChatGPT connectors

ChatGPT connectors expect a public HTTPS MCP endpoint (typically /mcp). A local desktop sidecar executable is not enough by itself. To use IconVectors from ChatGPT, you need an HTTP-accessible MCP wrapper that exposes the tools over HTTPS.

OpenAI Responses API

The OpenAI API MCP tool also expects a remote server_url. Because the model runs in OpenAI’s environment, it cannot call a local Windows executable on your machine directly.