Give your coding agent a consistent icon workflow.

Generate your private API key

Requirements: Node.js 20 or newer, an MCP-capable Codex installation, and an IconSearch account. First generate an API key from your account. IconSearch shows the complete key only once and gives you a ready-to-copy setup command.

1. Sign in on the account page and press Generate API key.
2. Copy the new key immediately. It begins with ics_live_.
3. Choose one Codex setup option below. You do not need to use both.

Treat the key like a password. Never put it in a project, GitHub commit, screenshot, chat message, or support ticket.

Connect Codex — choose one setup option

Both options create the same global Codex connection. Set it up once on each computer, not once for every project. You only need to edit it later if you replace or revoke the API key.

codex mcp add iconsearch --env ICONSEARCH_TOKEN=YOUR_API_KEY -- npx -y @iconsearch/mcp-server

codex --version
codex mcp list

where.exe npx

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null
notepad "$env:USERPROFILE\.codex\config.toml"

[mcp_servers.iconsearch]
command = "C:/Program Files/nodejs/npx.cmd"
args = ["-y", "@iconsearch/mcp-server"]

[mcp_servers.iconsearch.env]
ICONSEARCH_TOKEN = "PASTE_YOUR_NEW_KEY_HERE"

[mcp_servers.iconsearch]
command = "npx"
args = ["-y", "@iconsearch/mcp-server"]

[mcp_servers.iconsearch.env]
ICONSEARCH_TOKEN = "PASTE_YOUR_NEW_KEY_HERE"

Safe first test

In a new Codex task, paste this prompt. It searches only and explicitly prevents file changes:

Use IconSearch to find five icons for settings navigation. Do not change any files.

Codex desktop, Codex CLI, and the Codex IDE extension share the global ~/.codex/config.toml on the same computer. Do not add this block to every repository. See the official Codex MCP documentation .

How the system works

Configure another MCP client

Use this standard stdio configuration when your client accepts JSON MCP server settings:

{
  "mcpServers": {
    "iconsearch": {
      "command": "npx",
      "args": ["-y", "@iconsearch/mcp-server"],
      "env": { "ICONSEARCH_TOKEN": "YOUR_API_KEY" }
    }
  }
}

Replace YOUR_API_KEY with the key shown once on your IconSearch account page. Keep this configuration outside your repository. Set ICONSEARCH_PROJECT_ROOT only if the client starts the server outside your repository. For local development, ICONSEARCH_API_BASE may use a loopback HTTP URL; every non-local endpoint must use HTTPS.

Use the project-aware workflow

1. Read iconsearch_get_project_icons before choosing a new icon.
2. Reuse an existing semantic assignment when it already represents the requested purpose.
3. Search with product intent such as “billing history” instead of guessing a package export.
4. Retrieve the exact candidate and review its source and licence requirements.
5. Save only after the icon is approved; then audit before shipping.

All ten available tools

Project manifest

The first save creates iconsearch.json and stores sanitized files under .iconsearch/icons. Commit both so teammates and agents share the same decisions.

{
  "version": 1,
  "style": {
    "preferredLibraries": ["lucide"],
    "defaultSize": 20,
    "color": "currentColor",
    "strokeWidth": 2
  },
  "icons": {}
}

Each saved icon records a SHA-256 checksum, original library and name, source attribution, licence metadata, and the time it was approved.

Security model

Review changes produced by any coding agent before committing or deploying them.

Verify that everything is working

npm view @iconsearch/mcp-server version license

1. The npm command should report version 0.2.0 and licence MIT.
2. If you used Option A, codex mcp list should include a server named iconsearch. If you used Option B, check with /mcp in a new Codex task.
3. Ask Codex to call iconsearch_status; it should report connected: true without showing your key.
4. Ask for “billing history.” Search should return relevant candidates such as a receipt or history icon.
5. Return to your account page. The key should now say Last used with a recent date.
6. In a test repository, approve one icon, save it, and confirm that only iconsearch.json and .iconsearch/icons changed.
7. Run iconsearch_audit_project_icons and review the report before committing.

Technical verification only: inspect the published IconSearch package on npm .

Troubleshooting

PowerShell says codex is not recognized.

The Codex CLI is not available in that terminal. Use the manual global config in Option B; the desktop app can still load IconSearch from that file.

The npx command is missing or fails to start.

Install Node.js 20 or newer, reopen the terminal, and run the install command again.

IconSearch does not appear after I changed config.toml.

Check for duplicate IconSearch blocks or a wrong npx.cmd path, save the file, fully exit Codex, and start a new task after reopening it.

The server says the Agent API is not configured.

The production Supabase project is missing the latest agent-usage migration. Apply it, then redeploy the website.

Search says authentication is required.

Generate a new API key and copy the complete setup command again. If you revoked or replaced a key, restart Codex after updating the configuration.

The server cannot find my project.

Start the MCP client from the repository or set ICONSEARCH_PROJECT_ROOT to an existing project directory.

An SVG could not be saved.

The icon may contain active or external content, the semantic name may not be kebab-case, or the destination may already exist.