Using the MCP server from an AI agent

Every imageupload.io user - free or Pro - 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 four 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.

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.

What's not in v1

• SSE and stdio transports - we only do JSON-RPC over HTTPS for now.
• Image editing tools - you upload, you get a URL, that's it.
• Streaming uploads - send the whole image in one request.

If you need any of these, open an issue.

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.