How to Use Iconly MCP with the OpenAI Responses API

The OpenAI Responses API can call remote Model Context Protocol servers through its built-in mcp tool. Iconly exposes a remote Streamable HTTP server with account-aware tools for generating icons, vectors, social creatives, emails, and reusable brand assets.

This approach is useful when the model should choose and sequence design operations from a natural-language request. If your application already knows the exact operation and payload, the Iconly REST API may be the more deterministic integration.

How the Iconly and OpenAI Integration Works

Your backend
  └─ OpenAI Responses API
       └─ remote MCP tool
            └─ https://iconly.ai/mcp
                 └─ your authenticated Iconly account

Your backend sends the model a description of the remote server, a narrowly scoped tool list, and an authentication credential. OpenAI discovers the selected Iconly tool definitions and can request a call. When approval is enabled, your application receives an approval item before the tool runs.

Iconly tool group	Typical use	Suggested approval
Discovery	Tokens, presets, brands, media, library	Automatic only in trusted contexts
Generation	Icons, vectors, social creatives, emails	Always approve
Post-processing	Centering, thickness, recoloring, cleanup	Review arguments or scope narrowly
Persistence	Save assets or create prompt templates	Always approve

Configure OpenAI and Iconly Credentials

A single-account private backend needs two independent secrets:

• OPENAI_API_KEY authenticates your application to OpenAI.
• ICONLY_API_KEY authenticates the remote MCP request to your Iconly account.

Create the Iconly key under Iconly Settings → API Key, then store both values in your backend environment or secret manager:

OPENAI_API_KEY=your_openai_api_key
ICONLY_API_KEY=ik_your_iconly_api_key

Run a Read-Only Connection Test

Start by importing only check_tokens. This verifies the server URL, authentication, and tool discovery without authorizing a generation:

import os
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model=os.environ.get("OPENAI_MODEL", "gpt-5.6"),
    input="Check my Iconly token balance.",
    tools=[{
        "type": "mcp",
        "server_label": "iconly",
        "server_description": "Generate and manage design assets with Iconly.",
        "server_url": "https://iconly.ai/mcp",
        "authorization": os.environ["ICONLY_API_KEY"],
        "allowed_tools": ["check_tokens"],
        "require_approval": "never",
    }],
)

print(response.output_text)

Pass the raw Iconly ik_ value in authorization. Do not add the word Bearer to the value yourself.

Add Icon Generation with Approval

After the read-only test succeeds, expose only the operations needed by your feature. The following configuration supports preset discovery, icon generation, and saving while requiring approval for calls:

iconly_tool = {
    "type": "mcp",
    "server_label": "iconly",
    "server_description": "Generate and manage design assets with Iconly.",
    "server_url": "https://iconly.ai/mcp",
    "authorization": os.environ["ICONLY_API_KEY"],
    "allowed_tools": [
        "list_presets",
        "generate_icon",
        "save_to_library",
    ],
    "require_approval": "always",
}

first = client.responses.create(
    model=os.environ.get("OPENAI_MODEL", "gpt-5.6"),
    input=(
        "Create a centered blue line icon of a shopping cart. "
        "Keep even padding and do not save it yet."
    ),
    tools=[iconly_tool],
)

approval = next(
    item for item in first.output
    if item.type == "mcp_approval_request"
)

Show the approval request's tool name and arguments to the user. If they approve, continue the response with the approval item:

second = client.responses.create(
    model=os.environ.get("OPENAI_MODEL", "gpt-5.6"),
    previous_response_id=first.id,
    tools=[iconly_tool],
    input=[{
        "type": "mcp_approval_response",
        "approval_request_id": approval.id,
        "approve": True,
    }],
)

print(second.output_text)

A multi-step request may produce more than one approval item. Implement approvals as a loop and keep displaying the exact tool and arguments rather than assuming that one approval authorizes an entire workflow.

Authentication for Multi-User OpenAI Applications

An Iconly API key works well when one private backend acts for one Iconly account. It is the wrong model when your product serves multiple Iconly users. Do not route every customer through one shared key.

For a multi-user product:

1. Implement Iconly OAuth discovery and the authorization-code flow with PKCE.
2. Send each person to Iconly to sign in and approve access.
3. Store access and refresh tokens encrypted and associate them with the correct application user.
4. Pass that user's current access token in the MCP authorization field.
5. Rotate refresh tokens and revoke the connection when the user disconnects Iconly.

This keeps plan checks, token balances, brands, and library assets isolated by Iconly account.

Security and Tool Design

Import the smallest useful tool set

If a feature only generates draft icons, do not expose email, social, brand, or persistent-write tools. A smaller tool surface reduces schema overhead and accidental calls.

Separate generation from saving

Icon and vector tools return temporary results. Let the user review the asset before approving save_to_library. This keeps the library clean and makes persistent changes explicit.

Validate arguments before approval

Authentication identifies an account; it does not prove that every model-assembled tool call matches the user's intent. Display and validate the subject, quantity, brand, media references, and other cost-bearing inputs.

Use server-side logs carefully

Record tool names, timing, result status, and internal request IDs. Avoid logging bearer credentials, raw refresh tokens, or unnecessary brand and media content.

Example OpenAI and Iconly Workflows

Approved ecommerce icon set

1. Automatically list relevant presets.
2. Request approval for the first anchor icon.
3. Let the user inspect spacing, stroke, color, and background.
4. Use the approved asset as a reference for related subjects.
5. Approve permanent saves separately.

Brand-aware campaign assistant

Allow the model to list brands and media in an authenticated workspace, then request approval before generating social or email output. Keep publishing and sending outside the MCP workflow so a user can review the final rendered creative.

Conversational planning with deterministic delivery

Use MCP to let the model plan, discover resources, and produce drafts. After approval, hand stable identifiers to a deterministic REST workflow for high-volume generation, export, or downstream automation.

Troubleshooting OpenAI MCP Calls

The MCP request returns 401 Unauthorized

Confirm that ICONLY_API_KEY contains the current raw ik_ value, not your OpenAI key and not a value prefixed with Bearer. Rotate the Iconly key if it may have been exposed.

The response stops at an approval request

This is expected when require_approval is enabled. Read the mcp_approval_request, collect the user's decision, and continue with an mcp_approval_response tied to the previous response.

The model cannot find an Iconly tool

Check allowed_tools. OpenAI can only use tools imported by the request. Also verify that the authenticated Iconly plan supports the requested capability.

The generated icon is missing from the library

Generation returns a temporary image_id. Call save_to_library with that ID after review if you want a permanent library item.

A social or email call is rejected

Run check_tokens, verify the account plan, and confirm all brand, media, icon, and set IDs belong to the authenticated Iconly user.

Frequently Asked Questions

What server URL goes in the OpenAI MCP tool?

Use https://iconly.ai/mcp.

Does OpenAI need the Iconly API key?

The OpenAI API itself does not own the key. Your backend passes an Iconly API key or per-user OAuth access token in the remote MCP tool's authorization field.

Do Iconly MCP calls consume tokens?

Generation calls follow the authenticated Iconly account's normal token costs and plan checks. Read-only discovery and several deterministic post-processing operations do not generate new AI assets.

Can I connect Iconly through the Claude UI instead?

Yes, but the setup is different because Claude provides a hosted connector and OAuth interface. See the dedicated Iconly MCP for Claude guide.

For the complete tool list and compact copy-ready examples, use the Iconly MCP documentation.