map_icons
Finds an icon for each of up to 40 service or product names in one call, such as the services of an architecture. It is a workflow of the MCP server and the HTTP API, with the title "Map icons".
TL;DR
| Question | Answer |
|---|---|
| What is it? | A workflow: one call does the work of several tools and returns one combined answer. |
| What does it do? | Finds an icon for each of up to 40 service or product names in one call, such as the services of an architecture. |
| What does it replace? | up to 40 search_icons calls. |
| How do I call it over HTTP? | POST /v1/icons/map |
| Does it change anything? | No. It is read-only and idempotent, and it talks to nothing outside itself. It saves no file and returns its answer as data. |
| Which bounds apply? | maxIconNames, maxIconNameLength, maxIconAlternatives, maxIconCandidates. See the bounds below. |
| Where do I read its schema as data? | An MCP client gets the name, description, and JSON Schema of every tool from tools/list. |
What it does
Workflow. Finds an icon for each of up to 40 service or product names in one call, such as the services of an architecture. For every name it returns the best provider:name icon with a confidence (exact, strong, or ambiguous) and up to 3 alternatives. It never guesses: a name that could mean several icons (a kind of service several clouds offer, or a match by idea only) comes back with resolved false and candidates to choose from, and a name that matches nothing is listed in gaps with a neutral fallback icon. Set provider to the cloud the architecture runs on, so "queue" finds that cloud's product first. Reads the bundled icons and, when hosted, the organisation icons (org:name). Replaces up to 40 search_icons calls.
Steps
| Operation | Runs | What it does |
|---|---|---|
searchIcons | always | Search the bundled icons for a name or an idea. |
One call performs at most 80 operations.
Example call
The arguments of the call, as JSON:
{ "names": [ "S3", "Postgres", "Lambda", "load balancer", "queue" ], "provider": "aws"}Prompts that lead to it
- Which icons should I use for S3, Lambda, Postgres and a queue on AWS?
- Pick icons for every service in this architecture.
Arguments
| Field | Type | Required | Description |
|---|---|---|---|
names | string[] | yes | Services, products, or ideas to find icons for, written as the user wrote them ("S3", "Postgres", "load balancer"). Up to 40 names of up to 80 characters. |
provider | "aws" | "gcp" | "azure" | "alibaba" | "oci" | "ibm" | "cloudflare" | "digitalocean" | "vercel" | no | The cloud the architecture runs on. A name is looked up there first, so "queue" finds aws:sqs for aws. Omit it when the names are not tied to one provider. |
Result
| Field | Type | Required | Description |
|---|---|---|---|
provider | "aws" | "gcp" | "azure" | "alibaba" | "oci" | "ibm" | "cloudflare" | "digitalocean" | "vercel" | null | yes | The provider hint that was used, or null. |
results | object[] | yes | One entry per name that matched something, in the order sent. |
results[].name | string | yes | The name exactly as it was sent. |
results[].resolved | boolean | yes | True when icon holds the one icon to use. False when the name could mean more than one: choose from candidates, or ask the user. |
results[].icon | string | null | yes | The icon to write as icon=, such as aws:lambda; null when resolved is false. |
results[].confidence | "exact" | "strong" | "ambiguous" | yes | exact: the name is the icon or product name. strong: the name clearly points at this icon and no other provider competes. ambiguous: several icons fit, or the match is by idea only. |
results[].alternatives | string[] | yes | Up to 3 other icons that also fit a resolved name, best first. Empty when none. |
results[].candidates | string[] | yes | When resolved is false, the icons that fit, best first (up to 4). Empty when resolved. |
gaps | object[] | yes | Names that matched nothing, in the order sent. |
gaps[].name | string | yes | The name that matched no icon. |
gaps[].fallback | string | yes | A neutral icon to use instead, or leave icon= out so the node type draws its own. |
gaps[].reason | string | yes | Why there is no match, and what to try. |
resolvedCount | integer | yes | How many names have one icon to use. |
ambiguousCount | integer | yes | How many names need a choice from candidates. |
gapCount | integer | yes | How many names matched nothing. |
Behavior hints
| Hint | Value |
|---|---|
readOnlyHint | true |
destructiveHint | false |
idempotentHint | true |
openWorldHint | false |
Bounds
A bound that is reached is reported in the result; nothing is cut silently.
| Bound | Value | What it limits |
|---|---|---|
maxIconNames | 40 | Names in one call. |
maxIconNameLength | 80 | Characters in one name. |
maxIconAlternatives | 3 | Other icons listed beside a chosen icon. |
maxIconCandidates | 4 | Icons listed for a name that could mean several. |
See also
| Doc | Why |
|---|---|
| Tool reference | Every tool, with the workflows first |
POST /v1/icons/map | The same operation over HTTP |
| Language reference | What the diagram source may contain |
| Writing diagrams with an agent | The loop in practice |