IconSearch MCP Setup Guide for Coding Agents

Generate a key and connect Codex

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 once and gives you a ready-to-copy setup command.

terminal

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

Sign in on the account page and press Generate API key.
Copy the complete setup command shown beside the new key and run it in your terminal.
Restart Codex, then ask it to call iconsearch_status.
Run codex mcp list if you need to confirm the server configuration.

Keep the key private. Do not put it in your repository, screenshots, or messages. Codex stores MCP configuration in ~/.codex/config.toml. See the official Codex MCP documentation .

How the system works

1. Codex starts IconSearch

The npm package runs locally and tells Codex which icon tools are available.

2. Your key proves access

The private API key identifies your account. It can be revoked from the account page at any time.

3. The website answers

Search and exact-icon requests go to the authenticated IconSearch API, where access and daily usage are checked.

4. Decisions stay with the code

Approved SVGs and their semantic names are saved locally so every teammate and agent can reuse them.

Configure another MCP client

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

configuration

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

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

All ten available tools

iconsearch_start_sign_in

Start the secure browser device sign-in flow.

iconsearch_finish_sign_in

Finish an approved sign-in and store the revocable local session.

iconsearch_status

Check the account connection without exposing the token.

iconsearch_sign_out

Remove the locally saved IconSearch session.

iconsearch_get_project_icons

Read visual defaults and approved semantic icon assignments.

iconsearch_search

Search by intent, collection, style, licence safety, and page.

iconsearch_get_icon

Retrieve exact sanitized SVG plus source, author, and licence metadata.

iconsearch_save_project_icon

Save an approved SVG and update project memory. This changes files.

iconsearch_audit_project_icons

Report missing or changed managed files, inline SVGs, unmanaged assets, and mixed packages.

iconsearch_snippet

Create React, SVG, Vue, Svelte, Tailwind, or URL output for compatible workflows.

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.

configuration

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

Bounded writes

The save tool writes only the manifest and managed SVG directory inside a validated project root.

Symlink protection

Reads, writes, and audits refuse symlink traversal and filesystem-root projects.

Sanitized SVG

Scripts, embedded documents, event handlers, unsafe protocols, and external resources are rejected.

Revocable access

API keys are stored as unreadable fingerprints on the server, expire after 90 days, and can be revoked from your account.

Server-side limits

Authentication, plan access, and daily usage are checked before search or SVG retrieval.

No committed secrets

The project manifest stores icon decisions and checksums, never your API key.

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

Verify that everything is working

terminal

npm view @iconsearch/mcp-server version license
codex mcp list

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

Troubleshooting

The npx command is missing or fails to start.: Install Node.js 20 or newer, reopen the terminal, and run the install command again.
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.