Supericons lets AI coding agents search, recommend, and retrieve SVG icons from a semantic registry of 20,000+ free icons.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.7/5 across 5 of 5 tools scored.
Each tool has a distinct role: search for exploration, recommend for UI slots, get_icon for exact retrieval by ref, preview for refinement, and list_libraries for library metadata. Descriptions explicitly prevent confusion by directing usage order.
All tool names follow a consistent verb_noun pattern in snake_case (search_icons, list_libraries, get_icon, preview_icons, recommend_icons). This makes the API predictable and easy to navigate.
Five tools thoroughly cover the icon-serving workflow: search, retrieve, refine, recommend, and discover libraries. The count is neither bloated nor insufficient for the stated purpose.
The tool surface covers the full icon lookup and delivery lifecycle, including search, exact retrieval, previewing results, batch recommendations, and library discovery. No critical gaps like bulk operations or clarification handling are missing.
get_iconGet IconAInspectRetrieve one exact SVG icon using an exact ref returned by search_icons, recommend_icons, or preview_icons. Do not guess icon IDs. Use search_icons first if the user only described a concept. Returns SVG code, explicit public library labels, visual preview URL, and public semantic guidance for the exact icon.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Exact icon ID without the library prefix, for example "database", "user-circle", "brain-circuit", or "arrow-down". | |
| style | No | Optional style preference. Material Symbols supports outline and solid. Other hosted libraries report their verified styles in list_libraries. | any |
| library | Yes | Required library key for the exact icon. Supported values include si (Supericons AI and developer tool logos), lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons (Simple Icons brand logos), and mingcute. |
| Name | Required | Description |
|---|---|---|
| code | No | Stable error code when the exact icon is unavailable. |
| hint | No | Plain-language explanation of how to recover. |
| icon | No | Exact matching icon when found. |
| error | No | Recoverable error message when no exact icon is found. |
| next_step | No | Recommended next tool action. |
| retryable | No | Whether repeating the same exact lookup may succeed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false, so the description carries the burden for behavioral disclosure. It adds meaningful context: the id must come from prior tool outputs, and it discloses what is returned. However, it does not mention potential errors (e.g., invalid id/library) or whether it is purely read-only, though 'Retrieve' implies read-only. No contradictions with annotations exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the first states the function, the second gives a key rule and fallback, the third lists return values. No fluff, well front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with 3 params and an output schema. The description covers all essential aspects: what the tool does, how to get valid inputs, what to return, and when to use alternatives. With sibling context and schema present, it is complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description adds crucial semantics beyond the schema: the 'id' must be an exact ref returned by search_icons/recommend_icons/preview_icons, and users must not guess. This constrains how the parameters are used and reinforces the workflow, which the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves one exact SVG icon using an exact ref, and distinguishes it from search_icons by explicitly instructing to use search_icons for concepts. It names the exact return values (SVG code, labels, preview URL, guidance), making the purpose vivid and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: 'Do not guess icon IDs' and 'Use search_icons first if the user only described a concept.' It also references sibling tools (search_icons, recommend_icons, preview_icons) as sources of valid refs, clearly indicating when this tool is appropriate versus when to use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_librariesList LibrariesAList the free icon libraries available through the hosted Supericons MCP server. Use this before filtering by library or when a user asks which icon libraries are supported.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| libraries | Yes | Free icon libraries available through this hosted MCP server. |
| publicRecordCount | Yes | Number of public semantic icon records searchable through the hosted MCP server. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful context about it being a discovery step and the 'hosted' server scope, but no further behavioral details are necessary for a simple listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no redundant wording. The second sentence provides actionable usage guidance without extra fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-param list tool with full annotation coverage and an output schema, the description fully communicates what the tool does and when to use it. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100% by default. The description doesn't need to explain parameters; baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List the free icon libraries' – a specific verb and resource. It distinguishes itself from siblings like get_icon/search_icons by focusing on library discovery rather than individual icon retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'before filtering by library or when a user asks which icon libraries are supported.' This provides clear context and implies alternatives (e.g., use search_icons for actual icon lookup).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
preview_iconsPreview IconsARefine an icon result set or preview known icon refs returned by another Supericons tool. Use search_icons first for normal icon requests. Long icon lists are accepted and safely truncated to 12. Returns ready-to-use Markdown, a hosted preview fallback, a direct PNG image URL, and, when requested, an MCP image contact sheet.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Requested inline icon count. Values outside 1 to 12 are safely clamped with a warning. Numeric strings are accepted. | |
| query | No | Optional search query to preview visually, for example "license plate recognition camera scan car". | |
| style | No | Optional style preference. Unsupported values are ignored with a warning. | any |
| locale | No | Optional locale for multilingual search terms. Supported values: zh-Hans, zh-Hant, ja, ko, es, de, pt, ar, hi, vi, th. Unsupported values are ignored with a warning. | |
| library | No | Optional library key. Supported values include si (Supericons AI and developer tool logos), lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons (Simple Icons brand logos), and mingcute. | |
| icon_refs | No | Optional fixed icon refs in library:id format. Arrays, a single ref, and comma-separated refs are accepted. Up to 100 are accepted, 24 appear on the browser preview, and 12 are rendered inline. Larger lists are safely truncated with a warning. | |
| include_image | No | When true, include a PNG contact sheet as MCP image content. Boolean strings are accepted. A preview_url is always returned. |
| Name | Required | Description |
|---|---|---|
| error | No | Recoverable error message when preview inputs are missing or invalid. |
| query | No | Search query used for the visual preview, if any. |
| results | Yes | Icons included in the visual preview. |
| warnings | No | Unsupported optional inputs that were safely ignored. |
| image_url | No | Direct PNG URL for clients or Markdown renderers that can show remote images. |
| next_step | Yes | Useful next action for the caller. |
| preview_url | Yes | Browser URL for visual inspection. |
| image_included | Yes | Whether this response includes MCP image content. |
| markdown_image | No | Ready-made Markdown image snippet for final answers in clients that render remote Markdown images. |
| rendered_count | Yes | Number of icons rendered in the inline preview. |
| truncated_from | No | Original icon ref count when the input was truncated. |
| client_display_note | Yes | Plain-language note for clients that do not render images inline. |
| browser_preview_count | Yes | Number of accepted icon refs available at preview_url. |
| suggested_response_markdown | No | Ready-to-use answer with the image, refs, and browser fallback link. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: 'Long icon lists are accepted and safely truncated to 12' and the return format (Markdown, hosted preview fallback, direct PNG URL, MCP contact sheet). No contradiction found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: purpose first, usage guidance second, and behavioral detail third. Every sentence earns its place, with no verbosity or redundancy. It is highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 optional parameters) and 100% schema coverage, the description covers purpose, usage, and key behavioral traits. It could be more explicit about how the 'query' parameter can be used independently, but the schema fills that gap. Overall, the description is sufficiently complete for an agent to understand when and how to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all 7 parameters having descriptions. The tool description does not add significant parameter-specific meaning beyond what the schema already provides. It mentions truncation to 12, but the schema already documents limit and icon_refs behavior, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Refine an icon result set or preview known icon refs.' It also distinguishes from siblings by explicitly saying 'Use search_icons first for normal icon requests,' which positions this tool as a post-processing step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives direct guidance: 'Use search_icons first for normal icon requests' and implies this tool is for refining/previewing results from other Supericons tools. This explicitly names an alternative and sets clear context for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
recommend_iconsRecommend IconsAInspectRecommend a coherent icon set for up to 20 named UI slots in one call. Uses task context to narrow ambiguous meanings. When context is insufficient, returns needs_clarification with labeled interpretation options instead of guessing. Invalid inputs and service failures return a plain-language reason and a next step instead of a bare protocol error. Returns one recommendation and optional alternatives for each resolved slot, with explicit public library labels and visual preview URLs where available. Library key si means Supericons, not Simple Icons.
| Name | Required | Description | Default |
|---|---|---|---|
| task | No | Overall UI task, for example "choose icons for an AI dashboard sidebar" or "select bottom navigation icons for a finance app". Missing task text returns a structured recovery message. | |
| slots | No | List of 1 to 20 UI slots to fill, for example ["model", "prompt", "dataset", "evaluation"]. A single string is accepted as one slot. Larger lists return a structured split instruction. | |
| style | No | Optional style preference. Unsupported values are ignored with a warning. | any |
| locale | No | Optional locale for multilingual slot labels. Unsupported values are ignored with a warning. | |
| library | No | Optional library key when the user wants a consistent icon family. Supported values include si (Supericons AI and developer tool logos), lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons (Simple Icons brand logos), and mingcute. | |
| response_mode | No | Response size mode: plan, assets, or full. Unsupported values use plan with a warning. | plan |
| limit_per_slot | No | Number of choices per slot. Values outside 1 to 5 are clamped with a warning. Numeric strings are accepted. | |
| include_query_frame | No | Optional public-safe diagnostics for query understanding. Boolean strings are accepted. Leave false for normal compact responses. |
| Name | Required | Description |
|---|---|---|
| code | No | Stable error code for programmatic recovery. |
| hint | No | Plain-language recovery instruction. |
| task | Yes | Original UI task. |
| error | No | Plain-language reason the recommendation did not complete. |
| style | No | Style preference used for recommendations. |
| status | No | HTTP status from a hosted dependency failure. |
| details | No | Structured limits or failure details. |
| library | No | Library filter used for recommendations, if provided. |
| results | Yes | Recommended icon choices grouped by requested UI slot. |
| warnings | No | Unsupported optional inputs that were safely ignored or clamped. |
| next_step | No | Useful next action for the caller. |
| retryable | No | Whether a corrected or later request may succeed. |
| slot_count | Yes | Number of UI slots requested. |
| preview_url | No | Browser URL for visual inspection of the recommended icon set. |
| query_frame | No | Optional public-safe query understanding diagnostics for the task. |
| response_mode | Yes | Response size mode used for this recommendation. |
| search_runtime | No | Search execution path used for this recommendation. |
| all_slots_resolved | Yes | Whether every requested slot received a recommendation without clarification. |
| clarification_slots | Yes | Slots that need the caller to choose an interpretation. |
| needs_clarification | Yes | Whether one or more ambiguous slots require more context. |
| retry_after_seconds | No | Seconds to wait before retrying a rate-limited recommendation. |
| fallback_recommended | Yes | Whether the caller should consider direct search or clarification. |
| low_confidence_slots | Yes | Slots whose result is missing or has low confidence. |
| suggested_response_markdown | No | Plain-language explanation suitable for the agent response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the false hints in annotations by detailing ambiguity resolution via needs_clarification, plain-language error recovery with next steps, output structure with alternatives and preview URLs, and the specific 'si means Supericons, not Simple Icons' caveat. This substantially enriches behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact paragraph where every sentence adds value, starting with the core purpose, then covering edge cases and error behavior. It avoids redundancy with schema descriptions and is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, full schema coverage, and an output schema, the description covers key aspects: batch size limits, ambiguity handling, error recovery, output format, and a critical library name disambiguation. The only minor gap is sibling differentiation, but that is not essential given the clear purpose and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Even though schema coverage is 100%, the description adds crucial meaning beyond the schema: it clarifies the si library key, notes that numeric strings are accepted for limit_per_slot, and explains clamping and warning behaviors. This directly improves parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Recommend a coherent icon set for up to 20 named UI slots in one call,' clearly stating the verb (recommend), resource (icon set), and scope (batch). It distinguishes from siblings like search_icons by emphasizing coherence and multi-slot batching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool's context (batch icon recommendation with task context and ambiguity handling), but does not explicitly state when to use it instead of sibling tools like search_icons or list_libraries. The context is clear, but explicit exclusions or alternative references are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_iconsSearch IconsAInspectUse this as the main icon tool. Search 20,000+ curated SVG icons across 11 libraries by meaning, label, visual description, tags, and synonyms. When matches exist, the response includes a paste-ready suggested answer, a direct preview image, and Markdown that can show the image in the final reply. When no supported match exists, it returns an honest structured no-result with a next step and no fabricated icon. Library key si means Supericons, not Simple Icons.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of icons from 1 to 50. Numeric strings are accepted. | |
| query | Yes | Icon concept or search phrase, for example "database", "user profile", "chill", "trash", "upload cloud", "AI model", or "beautiful". | |
| style | No | Optional style preference. Unsupported values are ignored with a warning. | any |
| locale | No | Optional locale for multilingual search terms. Supported values: zh-Hans, zh-Hant, ja, ko, es, de, pt, ar, hi, vi, th. Unsupported values are ignored with a warning. | |
| library | No | Optional library key only when the user named a library. Omit it to search all libraries. Do not use all as a library key. Supported values include si (Supericons AI and developer tool logos), lucide, tabler, phosphor, heroicons, bootstrap, iconoir, ionicons, material, simpleicons (Simple Icons brand logos), and mingcute. | |
| library_mode | No | Optional library behavior. Omit it to use all when no library is named and strict when a library is named. Prefer requires a named library. All searches every eligible library. Unsupported or incomplete combinations are safely normalized with a warning. | |
| include_query_frame | No | Optional public-safe diagnostics for query understanding. Boolean strings are accepted. Leave false for normal compact responses. |
| Name | Required | Description |
|---|---|---|
| code | No | Stable code for a structured no-result. |
| hint | No | Plain-language recovery hint for a structured no-result. |
| error | No | Plain-language error for a structured no-result. |
| status | No | HTTP status from an upstream search failure. |
| details | No | Structured rate-limit or upstream failure details. |
| results | Yes | Matching icons with SVG code and semantic guidance. |
| warnings | No | Unsupported optional inputs that were safely ignored. |
| image_url | No | Direct PNG URL when usable icons exist. |
| next_step | Yes | Useful next action for the caller. |
| retryable | No | Whether changing the query or filters may produce a result. |
| limit_scope | No | Allowance scope reported by a rate limit. |
| preview_url | No | Browser URL for visual inspection of this search result set. |
| query_frame | No | Optional public-safe query understanding diagnostics. |
| library_mode | Yes | Library behavior used for this search. |
| outcome_type | No | Whether this response contains results, an honest no-match, or a tool failure. |
| result_count | No | Number of verified icons returned by this search. |
| markdown_image | No | Ready-made Markdown image when usable icons exist. |
| search_runtime | No | Search execution path used for this request. |
| top_result_ref | No | Top ordered icon ref when results exist. |
| requested_library | Yes | Preferred or required library, when supplied. |
| retry_after_seconds | No | Seconds to wait before retrying a rate-limited search. |
| result_interpretation | No | Plain-language guidance for interpreting this result count and outcome. |
| suggested_response_markdown | Yes | Compact answer that accurately reflects this response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no meaningful annotations (all false), the description carries the full burden of disclosing behavior. It reveals that successful matches include a paste-ready answer, preview image, and Markdown, and that no-result responses are honest and structured without fabricated icons. It also clarifies a potential ambiguity with the 'si' library key, adding valuable transparency beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the key directive ('Use this as the main icon tool'). Every sentence earns its place, covering purpose, behavior on success, and behavior on failure without superfluous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters) and the presence of an output schema, the description sufficiently covers the main behavior, no-result handling, and a key library-key nuance. It does not need to explain return values since the output schema does that, and it remains complete and actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by explaining search dimensions (by meaning, label, visual description, tags, synonyms) and clarifying that 'si' means Supericons, not Simple Icons. This goes slightly beyond the schema's parameter descriptions, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Use this as the main icon tool' and clearly states the tool's function: searching 20,000+ curated SVG icons across 11 libraries. It specifies the search dimensions (meaning, label, visual description, tags, synonyms), which distinguishes it from sibling tools like get_icon or recommend_icons.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly directs users to use this as the main icon tool, establishing when to use it. It also describes what happens when matches do or do not exist. However, it does not mention alternatives like get_icon or recommend_icons, so users are not told when to choose those instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
