2026-04-08 · By imageupload.io editorial · Updated 2026-07-18

Using the MCP server from an AI agent

Every registered imageupload.io user gets an MCP endpoint and a bearer API key. This post shows how to use them.

What is MCP?

Model Context Protocol is an open standard for giving AI agents structured access to tools. Instead of teaching your model how to do HTTP multipart POSTs, you declare a tool with a JSON schema and the client handles the wire protocol. imageupload.io exposes seven tools:

upload_image - upload a base64-encoded image, get back a share URL and direct URL.
list_images - list every image owned by the bearer-authenticated user.
get_image - look up one image by slug.
delete_image - delete one image by slug.
list_folders - list folders with their image counts.
create_folder - create a folder for later uploads.
get_quota - inspect monthly API/MCP usage and plan limits.
list_folders - list folders with their image counts.
create_folder - create a folder for later uploads.
get_quota - inspect monthly API/MCP usage and plan limits.
list_folders - list folders with their image counts.
create_folder - create a folder for later uploads.
get_quota - inspect monthly API/MCP usage and plan limits.
list_folders - list folders with their image counts.
create_folder - create a folder for later uploads.
get_quota - inspect monthly API/MCP usage and plan limits.
list_folders - list folders with their image counts.
create_folder - create a folder for later uploads.
get_quota - inspect monthly API/MCP usage and plan limits.
list_folders - list folders with their image counts.
create_folder - create a folder for later uploads.
get_quota - inspect monthly API/MCP usage and plan limits.
list_folders - list folders with their image counts.
create_folder - create a folder for later uploads.
get_quota - inspect monthly API/MCP usage and plan limits.
list_folders - list folders with their image counts.
create_folder - create a folder for later uploads.
get_quota - inspect monthly API/MCP usage and plan limits.
list_folders - list folders with their image counts.
create_folder - create a folder for later uploads.
get_quota - inspect monthly API/MCP usage and plan limits.

Getting your API key

Sign in, go to /dashboard/profile, scroll to "API key (MCP)". Copy the iu_live_... token. Treat it like a password - anyone with the token can upload to your storage quota.

Discovery endpoint

Before authenticating, you can GET /mcp to get server info:

curl https://imageupload.io/mcp

Returns the transport, endpoint, and supported JSON-RPC methods.

Listing tools

curl -X POST https://imageupload.io/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

No auth required for tools/list - it's schema only.

Uploading an image

tools/call requires a bearer token:

curl -X POST https://imageupload.io/mcp \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer iu_live_YOUR_KEY' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "upload_image",
      "arguments": {
        "filename": "chart.png",
        "mime": "image/png",
        "data_base64": "iVBORw0KGgoAAAANS...",
        "expiration": "1w"
      }
    }
  }'

The response looks like:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "Uploaded. Share: https://imageupload.io/i/Ab3f9X2k" }],
    "structuredContent": {
      "slug": "Ab3f9X2k",
      "share_url": "https://imageupload.io/i/Ab3f9X2k",
      "direct_url": "https://imageupload.io/f/Ab3f9X2k.png",
      "size": 14321,
      "width": 800,
      "height": 600,
      "expires_at": 1775000000
    }
  }
}

Use the direct_url if you want to embed the image somewhere; use the share_url if you want to hand it to a human.

Claude Desktop config

If you're running Claude Desktop, drop this into claude_desktop_config.json:

{
  "mcpServers": {
    "imageupload": {
      "command": "npx",
      "args": ["-y", "@imageupload/mcp"],
      "env": { "IMAGEUPLOAD_API_KEY": "iu_live_YOUR_KEY" }
    }
  }
}

Claude will discover the tools automatically and use them when appropriate.

Rate limits and quotas

Free users: 100 MB of storage shared across all images. Expirations up to 3 months.
Pro users: unlimited storage and the "forever" expiration option.
All users: the upload_image tool respects the same per-image max (25 MB) and file-type allow-list as the web uploader.

Transport notes

The hosted endpoint accepts stateless JSON-RPC over HTTPS. The @imageupload/mcp npm package provides a stdio wrapper for Claude Desktop, Cursor, Windsurf, and other desktop clients. Upload calls send the complete image in one request; image editing is intentionally outside the service's scope.

Example: generate + upload + return URL

Here's a minimal Python snippet an agent might run:

import base64, requests

with open("plot.png", "rb") as f:
    data = base64.b64encode(f.read()).decode()

r = requests.post(
    "https://imageupload.io/mcp",
    headers={"Authorization": "Bearer iu_live_YOUR_KEY"},
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "upload_image",
            "arguments": {
                "filename": "plot.png",
                "mime": "image/png",
                "data_base64": data,
                "expiration": "1d"
            }
        }
    }
).json()

print(r["result"]["structuredContent"]["share_url"])

That's everything. Happy building.

Using the MCP server from an AI agent