MCP Server

QUICK START

Connect your client

Add the remote server to your client's MCP settings:

1. 1
   Get your API key

   Use an existing key or create one in the console. Store it securely.

2. 2
   Add the remote server

   Set the MCP URL to https://mcp.sukidata.com/mcp and send your key in the Authorization header.

3. 3
   Reload your client

   Confirm that Sukidata appears in the client's tool list.

{
  "mcpServers": {
    "sukidata": {
      "url": "https://mcp.sukidata.com/mcp",
      "headers": {
        "Authorization": "Bearer $SUKIDATA_API_KEY"
      }
    }
  }
}

Configuration filenames and environment-variable syntax vary by client. The endpoint and Bearer header above are the required connection values.

TOOLS

Web Data tools

Use get_result with the returned search ID to continue a pending search without creating another request.

IMAGES

Generate and edit images

Image generation usually takes 30 seconds to two minutes. Submit once, then use the returned task_id to retrieve the result.

{
  "model": "gpt-image-2.5",
  "prompt": "A blue ceramic cup on a white background",
  "idempotency_key": "cup-example-1",
  "size": "1254x1254",
  "quality": "high"
}

Upload local images

With a remote connection, your client reads the local file and sends a Base64 data URL. This example uses an already-connected MCP client; use image/jpeg or image/webp for those formats.

import { readFile } from "node:fs/promises";

const image = await readFile("./photo.png");
await client.callTool({
  name: "edit_image",
  arguments: {
    model: "gpt-image-2.5",
    prompt: "Replace the background with a snowy mountain",
    idempotency_key: "upload-edit-example-1",
    images: ["data:image/png;base64," + image.toString("base64")]
  }
});

For a mask, read a PNG file and pass its data URL in mask. Keep the file contents, arguments and idempotency_key unchanged when retrying the same submission.

Image parameters

{
  "task_id": "img_example",
  "wait_seconds": 20
}

Completed results include images with public URLs, dimensions, format, byte size and url_expires_at. Output settings and usage are included when available. Links are available for 31 days from publication and anyone with the URL can open the image; save files before expiry.

The tools/call result's content includes both URL resource links and ImageContent blocks (type: "image"). Each image block follows its link and contains the original image bytes as Base64, without resizing or changing metadata. Compatible clients can display or inspect the images directly. Remote HTTP and local stdio return the same format.

[
  { "type": "text", "text": "Image generation completed. 1 image(s)." },
  {
    "type": "resource_link",
    "uri": "https://files.sukidata.com/ai/images/example-token/img_example_0.png",
    "name": "image-1.png",
    "mimeType": "image/png"
  },
  {
    "type": "image",
    "mimeType": "image/png",
    "data": "<base64 image bytes>"
  }
]

Inline images are limited to 5 MiB each and 6 MiB total before Base64 encoding. Reading them may add up to 8 seconds after the task query. Larger images and images that could not be read retain their URLs, with a note in content. This does not change the task status or charge.

A timed-out wait does not cancel generation. If submission is interrupted, query the returned task ID; if no ID was returned, retry the original arguments with the same idempotency_key. A query error does not mean generation failed.

RESPONSES

Results and billing

Tools return a text summary in content and data in structuredContent. Web Data results include these fields; the search response is in data.

TROUBLESHOOTING

Troubleshooting

When connecting, HTTP 401 means the Bearer key is missing or malformed; 429 means the request limit was reached. Check your configuration or wait before retrying.

Tool failures set isError: true. The code and message in structuredContent.error describe the cause.

• auth_failed or scope_forbidden: check the key's status and product permissions.
• insufficient_credits or insufficient_ai_balance: add funds to the corresponding balance.
• rate_limited: wait before retrying the same operation.
• submission_unconfirmed: query the returned task ID, or retry the original arguments and idempotency_key if no ID was returned.
• image_status_unavailable or service_unavailable: if an ID was returned, query it again. Image generation may still be running.

Need help connecting? Email support@sukidata.com.