Docs/MCP

MCP

Icoustic is not an AI product. On the Mac it can speak MCP (Model Context Protocol) so your AI desktop apps — Claude, Cursor, ChatGPT Desktop, and similar — can ask real questions of your collection. Icoustic does not upload your catalog and does not call a model vendor. The server listens on your Mac only.

In the app this is Settings → AI Assistants (Settings → Connect is for devices on your network). MCP is included once Icoustic is unlocked — Lifetime, Monthly (including the 7-day trial), or a pre-1.4 paid download. A locked Mac will not serve MCP. Icoustic must stay open while a client uses MCP.

Icoustic speaks the current MCP `2026-07-28` spec (stateless core — no handshake, no sessions), and still accepts the legacy initialize flow from older clients during the ecosystem transition.

Give your AI the Icoustic skill

Download the Icoustic skill package so the assistants you already use know how the app works — and how to use MCP tools safely. Full install steps and the zip download are on that page.

Enable in Icoustic

Open Icoustic → Settings… → AI Assistants
Turn Allow AI assistants to use my library on
Confirm Status shows something like Ready on this Mac · 127.0.0.1:8741
Click Test connection — expect OK · N tools
Under Capability, leave Ask only for analysis, or switch to Suggest changes to stage proposals
Optionally turn on Notify when proposals arrive (background notifications; asks for OS permission)

Token controls on this pane: Show / Hide, Copy, and Rotate. Disabling AI Assistants stops the server and rotates the token. Connect each desktop app again so they pick up the new token. Last used updates when a client successfully talks to Icoustic.

Connect a desktop app

In Settings → AI Assistants → Connect (the Connect section on the AI Assistants pane — not Settings → Connect, which is for devices on your network), prefer the Connect buttons — they merge only the icoustic entry and leave your other assistants alone.

Cursor

Click Add to Cursor — Cursor opens an install prompt; approve icoustic. Or click Connect via config to merge into ~/.cursor/mcp.json (macOS may ask you to select that file once; access is remembered).
Open Customize → MCPs and confirm icoustic is on (green).
Ask: “Using Icoustic, how many tracks are in my library?”

Claude Desktop

Prefer the Desktop Extension (no Node.js). Local MCP is not Claude’s Settings → Connectors (that’s Anthropic’s cloud registry — Figma, Vercel, etc., and it cannot reach 127.0.0.1).

Click Install Claude extension (or download icoustic-claude.mcpb and open it).
Paste the token from Icoustic — use Show then Copy on the token row, or Copy token under Claude Desktop. Port defaults to 8741.
Fully quit Claude Desktop and reopen — extensions load at launch.
In a new chat, confirm icoustic under + → Connectors or Settings → Extensions, then ask about your library (not “connect to Icoustic MCP,” which makes Claude search the public connector directory).

Advanced fallback: open Advanced — MCP details and use Connect Claude via config file (requires Node.js for npx mcp-remote). macOS may ask you to select claude_desktop_config.json once; access is remembered.

ChatGPT Desktop

Click Connect ChatGPT Desktop — merges into ~/.codex/config.toml.
If macOS shows a permission error, select config.toml (or the .codex folder) in the file picker once. Press ⌘⇧. if the folder is hidden.
Restart ChatGPT Desktop / start a new session.
Confirm via ChatGPT’s Settings → MCP servers or type /mcp in the composer.

ChatGPT custom connectors

Not supported for local Icoustic MCP. ChatGPT web connectors only talk to public HTTPS endpoints from OpenAI’s cloud — they cannot reach loopback without a tunnel, and Icoustic does not ship tunnels. Use Cursor, Claude Desktop, or ChatGPT Desktop instead.

Ask only vs Suggest changes

The Capability picker:

Ask only — read-only: stats, search, missing metadata, genre audit, duplicate candidates, playlists, sources
Suggest changes — everything Ask only can do, plus propose_* tools that stage changes for review

Mutations are review-gated. Nothing is written to tags or your library until you approve it in the sidebar under MCP Actions — or until the model calls apply_proposal when Allow assistants to apply changes is on (default off; only available in Suggest changes).

Typical proposals include tag edits, artwork actions, playlists and smart playlists, marking compilations, duplicate resolution (index-remove only — files stay on disk), and rescans. Applied changes can be rolled back; every apply also keeps an index snapshot you can restore.

Advanced — MCP details

Expand Advanced — MCP details for the MCP endpoint URL, copyable Cursor / Claude / ChatGPT configs, Connect Claude via config file, and a copyable probe prompt.

Troubleshooting

Unauthorized / 401 — token rotated; Show / Copy the token or re-Connect
Connection refused — Icoustic not running, or AI Assistants off
Test connection fails — wait until Status is Ready, then retry
Tools missing — refresh MCP / restart the client after Connect
Permission error / file picker for config Connect — select ~/.cursor/mcp.json, Claude’s claude_desktop_config.json, or ~/.codex/config.toml (or the parent folder) once; Icoustic remembers. Prefer Add to Cursor / Install Claude extension when possible
ChatGPT connectors “can’t reach” — expected; use a desktop client above
Claude extension — use Install Claude extension; config-file fallback under Advanced still needs Node.js for npx

Privacy

Traffic stays on 127.0.0.1 between the client (or the Claude extension bridge) and Icoustic
Your AI client may send tool inputs and outputs to whatever model you chose — prefer a local model if you want zero third-party visibility of titles, artists, and paths
Icoustic itself does not collect or phone home MCP traffic