Developers

3D Icon API and MCP Server for Claude, Cursor and AI Agents

Two ways in. The MCP server lets an AI assistant search the library, look at icons, download files and generate new ones right inside the conversation. The REST API does the same searches and downloads for your own code. Both use one API key and bill credits exactly like the website.

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.

Every tool is part of the Studio plan. Search, details, 512px / original downloads, generation and your account all need a personal API key from a Studio account (Settings → API keys). Without a key, or with a key from a Free or Designer account, a client can connect and see the tool list, but every call is refused. The library itself stays free to browse and search on the website.

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/mcp

Connect a client

Three steps, about a minute.

  1. On a Studio plan, create an API key in Settings → API keys and copy it (it is shown once).
  2. Add the server to your client with the URL below and the Authorization header.
  3. 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.

  1. Sign in and open Settings → API keys.
  2. Click Create key, give it a label ("Claude Code", "Cursor"…), and copy the key. It starts with blu_live_ and is shown only once.
  3. Send it as the header Authorization: Bearer blu_live_… when you add the server.
  4. Rotate or revoke it from the same page whenever you like; the old key stops working immediately.
Open Settings → API keys
Keep it secret
  • 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.

ToolNeedsWhat it doesTry saying
search_iconsAPI keyFind 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_iconAPI keyFull 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_collectionsAPI keyThe curated collections (Christmas, Marketing essentials, …). Feed a collection into search_icons to browse it.“What themed collections do you have?”
get_accountAPI keyYour plan, credit balance, maximum download size and whether Studio generation is included.“How many credits do I have left?”
download_iconAPI keyA 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_iconAPI keyGenerate 1–4 new icons from a prompt with Studio, optionally using library icons as style references. Returns the image URLs and the expanded prompts (usually 1–2 minutes).“Generate a 3D icon of a red panda holding a coffee cup.”
list_generationsAPI keyYour 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. Downloading the same icon again, at any size, is free. Studio can take up to 60 new icons a day.
  • 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.
  • A key from a Free or Designer account can list the tools but not call them, the same as no key. Every tool needs a Studio account; upgrading turns them on for the same key.
  • 3D is a Studio-plan beta: generate_icon with kind "3d" is refused on other plans.
See pricing →
Plan caps
PlanMax download sizeStudio generation
Studio1024pxIncluded

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. Every tool call counts, search_icons included; connecting, listing the tools and get_account itself do not.
  • 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 seeDo this
401 “`get_icon` is part of the Studio plan and needs an API key”You connected without a key: the tools can be listed but not called. 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 have no MCP access. Upgrade to Studio on the Billing page; the same key starts working straight away.
The client says the server is unreachableCheck the URL ends in /api/mcp and uses https. Opening it in a browser should show a JSON card.
429 rate_limitedWait for the Retry-After seconds, then slow the automation down — the 300/min budget is per key.
429 monthly_limit_reachedThe account has used its 300 tool calls for the month. It starts again on the 1st; get_account still answers and reports the exact reset time.

REST API

The same library and billing, for your own code.

Plain HTTPS and JSON for servers, scripts and build pipelines. It reads the same catalogue and charges credits through the same code as the website and the MCP server.

  • Auth: the same personal API key as MCP — Authorization: Bearer blu_live_… — from a Studio account. A key from a Free or Designer account gets 403 plan_not_allowed.
  • 5,000 calls a month per account, counted separately from MCP. GET /api/v1/me is free and tells you how many are left.
  • Credits work exactly like the website: 256px downloads are free, and a high-res download is charged the first time you take that icon and free after that.
  • No generation endpoint yet. Generate on the website, or with the MCP server's generate_icon.
https://realisticicon.com/api/v1

Keep the key on your server. A key can spend your credits, so call the API from your backend, not from a web page. Send Content-Type: application/json with every POST: a POST without it is refused before it reaches the API.

# search
curl "https://realisticicon.com/api/v1/icons?q=fox&limit=5" \
  -H "Authorization: Bearer blu_live_YOUR_KEY"

# download — charged the first time you take this icon
curl -X POST "https://realisticicon.com/api/v1/icons/ICON_ID/download" \
  -H "Authorization: Bearer blu_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"size":"512"}'

REST endpoints

Six endpoints. JSON in, JSON out.

MethodPathWhat it doesCredits
GET/api/v1/iconsSearch or browse. Query: q, category, style (realistic · isometric · clay), kind (image · video), collection, page, limit (up to 50, default 24), seed, locale. Browse results include a seed: send it back with the next page so the order stays stable.—
GET/api/v1/icons/{id}One icon: description, tags, generator prompt, available sizes, the 256px preview and its page link.—
POST/api/v1/icons/{id}/downloadBody {"size": "256" | "512" | "original"} (default 512). Returns the file URL, whether this call was charged, and your new balance.256px free. 512px or original: 1 credit the first time per icon, then free. Up to 60 new icons a day.
GET/api/v1/collectionsCurated collections, optionally filtered by theme. Pass a collection's id as collection= to /icons to list its icons.—
GET/api/v1/generationsYour recent Studio runs with their image URLs (limit up to 40).—
GET/api/v1/meYour plan, credits, largest download size and this month's API calls. Does not count toward the 5,000.—

GET /api/v1 needs no key and returns a JSON card listing these endpoints. Add locale=th (or any site language) to get titles and page links in that language.

REST errors & limits

Standard status codes, one JSON shape.

Every error looks like { "error": { "code": "…", "message": "…" } }. Branch on code, which stays the same; message is written for people and may change.

StatuscodeWhat it means
400invalid_requestA parameter is missing or out of range. The message names it.
401missing_api_key · invalid_api_keyNo key, or the key is wrong, rotated or revoked.
402insufficient_creditsNot enough credits for that download. Top up on the Billing page.
403plan_not_allowed · over_plan_capThe key's account is not on Studio, or the size is above the plan's cap.
404not_foundNo such icon, collection or endpoint.
405method_not_allowedRight path, wrong method. The Allow header lists the right one.
429rate_limited · monthly_limit_reached · daily_limit_reached300 requests a minute per key (wait Retry-After), 5,000 calls a month (resets at X-Quota-Reset), or the plan's daily limit of new icon downloads (resets at midnight UTC).
5xxupstream_unavailable · internal_errorA problem on our side. Retrying is safe: the same icon is never charged twice.
Headers on every answer
  • X-RateLimit-Limit and X-RateLimit-Remaining: this minute.
  • X-Quota-Limit, X-Quota-Remaining and X-Quota-Reset: this month (UTC).
  • Retry-After: on every 429, in seconds.

Ready to try it?

On Studio: create a key, then add the URL to your assistant or call the REST API from your code.