What the MCP server does
MCP (Model Context Protocol) is the open standard AI apps use to call external tools.
Once connected, the assistant decides on its own when to call our tools. Ask for "a cute 3D fox for my app icon" and it searches the library, shows you previews, and can hand you the download URL or generate a fresh variation — without you opening the website.
- Search ~12,000 icons by keyword, category, style (realistic / isometric / clay) or curated collection.
- See an icon: get_icon attaches a real preview image, so a multimodal assistant can judge it.
- Download 512px or original files, and generate new icons with Studio — billed exactly like the website.
Search is free; the rest is Studio. search_icons works without a key — up to 100 calls a day — so you can connect and try it right now. Everything else (details, 512px / original downloads, generation, your account) is part of the Studio plan and needs a personal API key from a Studio account (Settings → API keys). A key from a Free or Designer account gets search only.
The endpoint
One URL, Streamable HTTP transport, no session state.
Every MCP-capable client takes a server URL. Ours is:
Opening it in a browser returns a small JSON card with the tool list. Clients talk JSON-RPC to it over POST; you never call it by hand.
https://realisticicon.com/api/mcpConnect a client
Three steps, about a minute.
- On a Studio plan, create an API key in Settings → API keys and copy it (it is shown once).
- Add the server to your client with the URL below and the Authorization header.
- Ask the assistant for an icon. It will discover the tools by itself.
Verify: ask “which tools do you have from realisticicon?” — the assistant should list search_icons, get_icon and friends.
# the key is required — MCP is part of the Studio plan
claude mcp add --transport http realisticicon https://realisticicon.com/api/mcp \
--header "Authorization: Bearer blu_live_YOUR_KEY"Run once in a terminal. Use `--scope user` to make it available in every project. `claude mcp list` shows the connection status.
API keys
A key connects the server to your Studio account and its credits.
- Sign in and open Settings → API keys.
- Click Create key, give it a label ("Claude Code", "Cursor"…), and copy the key. It starts with blu_live_ and is shown only once.
- Send it as the header Authorization: Bearer blu_live_… when you add the server.
- Rotate or revoke it from the same page whenever you like; the old key stops working immediately.
- A key can spend your credits (downloads, generation). Treat it like a password.
- It cannot change your account, buy credits or create more keys — those need a browser sign-in.
- You can have up to 10 active keys; use one per tool so you can revoke them independently.
Tools
What the assistant can call. Every tool returns readable text plus structured data.
| Tool | Needs | What it does | Try saying |
|---|---|---|---|
search_icons | nothing | Find icons by keyword, category, style, kind (image / video) or collection. Returns a page of results with 256px preview URLs and page links. | “Find me 3D icons of a coffee cup in clay style.” |
get_icon | API key | Full details of one icon — description, tags, generator prompt, available sizes — plus the 128px image so the assistant can see it. | “Show me the second one and tell me what sizes it comes in.” |
list_collections | API key | The curated collections (Christmas, Marketing essentials, …). Feed a collection into search_icons to browse it. | “What themed collections do you have?” |
get_account | API key | Your plan, credit balance, maximum download size and whether Studio generation is included. | “How many credits do I have left?” |
download_icon | API key | A direct file URL at 256px (free), 512px or the original PNG. Charges credits the first time you take a high-res version of an icon; re-downloads are free. | “Download that fox at 512px.” |
generate_icon | API key | Generate 1–4 new icons from a prompt with Studio, optionally using library icons as style references. Returns the image URLs and the expanded prompts (about 30–90 seconds). | “Generate a 3D icon of a red panda holding a coffee cup.” |
list_generations | API key | Your recent Studio runs, newest first, with image URLs and prompts — so the assistant can reuse an earlier result instead of spending credits again. | “Show me the icons I generated last time.” |
Credits & plans
The same rules as the website — the MCP server calls the same billing code.
- 256px and smaller: no credits, but still a key call like everything else.
- 512px and the original: 1 credit the first time you download an icon (5 on the Studio plan). Downloading the same icon again, at any size, is free.
- Studio generation: charged per image at the Studio rate, reserved before the run and refunded for any image that fails.
- If you run out of credits the tool tells the assistant, which will point you to Billing instead of retrying.
- MCP is sold on the Studio row only: a key from a Free or Designer account cannot connect at all, not even to search. Upgrading to Studio is what turns the server on.
- 3D is a Studio-plan beta: generate_icon with kind "3d" is refused on other plans.
| Plan | Max download size | Studio generation |
|---|---|---|
| Studio | 1024px | Included |
Example prompts
Things that work well once the server is connected.
- “I need an app icon for a habit-tracking app. Show me 6 realistic 3D options.”search_icons → previews inline → follow up with “the third one, in isometric style” to refine.
- “Which of these three icons fits a dark navy background best?”get_icon on each → the assistant looks at the actual images before answering.
- “Give me the original file of the arctic fox icon.”get_account (checks your plan) → download_icon size=original → a URL you can save.
- “Make a clay-style 3D icon of a rocket in the same style as icon cute-shiba-inu-icon.”generate_icon with referenceIconIds → new PNGs, also saved to your Studio history.
Limits
Generous for a person, tight for a runaway loop.
- 300 tool calls a month, the allowance on the Studio card. get_account tells you how many are left and when the month rolls over; connecting, listing the tools and get_account itself do not count.
- 300 requests per minute per key (a request without one never reaches a tool). Over that you get a 429 with Retry-After.
- Search returns at most 50 icons per page — page through with page and the seed the tool gives you.
- generate_icon runs synchronously and can take up to a couple of minutes; count is capped at 4 images per call.
- Preview images attached to results are downscaled to 256px to keep the conversation light.
Troubleshooting
What the assistant will tell you, and what to do.
| You see | Do this |
|---|---|
| 401 “`get_icon` is part of the Studio plan and needs an API key” | You connected without a key, which covers search_icons only. Create one in Settings → API keys on a Studio account and add the Authorization header, then reconnect. |
| “The API key was rejected (invalid_api_key / api_key_revoked)” | Typo, or the key was rotated / revoked. Copy the current key from Settings, or create a new one. |
| “Not enough credits” | Top up or upgrade on the Billing page. 256px downloads keep working for free. |
| 403 “`download_icon` is included in the Studio plan only” | The key is valid but the account is on Free or Designer, which get search_icons only. Upgrade to Studio on the Billing page; the same key starts working straight away. |
| The client says the server is unreachable | Check the URL ends in /api/mcp and uses https. Opening it in a browser should show a JSON card. |
| 429 rate_limited | Wait for the Retry-After seconds, then slow the automation down — the 300/min budget is per key. |
| 429 monthly_limit_reached | The account has used its 300 tool calls for the month. It starts again on the 1st; get_account and search_icons still answer, and get_account reports the exact reset time. |
| 429 daily_limit_reached | Keyless search is capped at 100 calls a day per address (per account with a Free or Designer key). It frees up over the next 24 hours; a Studio key is not capped this way. |
Ready to try it?
On Studio: create a key, add the URL to your assistant, and ask for an icon.