Add image search to Claude and Cursor with MCP

The server speaks Streamable HTTP and signs you in with OAuth: the first time your client connects, it opens a Pix4Less page in your browser, so there is no API key to copy. Each tool calls the same /v1 API, so prices, limits and errors match the JSON API.

Claude

In Claude on the web, desktop or mobile, open Settings, Connectors, Add custom connector, paste the URL, and click Connect. The Add to Claude link opens that dialog with everything filled in. Connectors you add in Claude also show up in Claude Code.

https://pix4less.com/mcp

Claude Code

claude mcp add --transport http pix4less https://pix4less.com/mcp

Then type /mcp in Claude Code, pick pix4less and choose Authenticate. Add --scope user to the command to use it in every project.

Cursor

Paste this into ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one. Then open Cursor Settings, MCP and click Connect next to pix4less.

{
  "mcpServers": {
    "pix4less": {
      "url": "https://pix4less.com/mcp"
    }
  }
}

ChatGPT, VS Code, Codex, Gemini CLI and Antigravity have their own steps, and there is a prompt that lets your agent install the server itself. Both are in the MCP docs.

Your browser opens pix4less.com. Sign in, or create an account on the way; Google sign-in takes one click. A new account receives a one-time trial grant of 100 credits once its email address is verified (signing in with Google counts as verified). Signup needs no payment; searches and new downloads use credits.

Pix4Less then shows which app is asking and what it will be able to do. Click Allow and the browser hands you back to your client. You can see and disconnect connected apps in your dashboard.

To check the connection, ask your agent to call list_collections. It is free.

Scripts and CI, or a client that cannot sign in, can use an API key from the dashboard instead, sent as an Authorization: Bearer header. The MCP docs show how.

Ask in plain language and name the server so the agent does not guess:

Use pix4less to find three landscape photos of a quiet coffee shop. Show me the previews, and tell me each image's id, title and license before we pick one.

Behind that prompt the agent calls search_images. These are its arguments; query is the only one you need, and include_previews asks for small JPEG thumbnails so the agent (and you) can judge the pictures visually.

{
  "query": "quiet coffee shop interior, morning light",
  "orientation": "landscape",
  "per_page": 3,
  "include_previews": true
}

Search finds existing catalog images and never generates one. It returns up to 12 matches per call, in blended-relevance order, so keep that order rather than re-sorting. Start with a broad subject; extra details and hard filters can produce zero matches.

Response fields. The result is JSON with these top-level fields: data (the images), pagination, search_type, session_id, shuffle_cycle_restarted and request_id. Each item in data carries:

• id, title, description (the description doubles as alt text) and tags
• url and renditions: preview paths on https://pix4less.com, never the original file
• width, height, orientation, aspect_ratio, megapixels and format, which describe the original
• quality_tier and download_credits, an indicative download price
• license (code, url, status) and content_warnings
• match_confidence and search_match, a retrieval estimate and the ranking model’s verdict, not a probability or a quality guarantee

To see more matches, send back the session_id from the previous response as the session_id argument (“load more”).

Search results already include previews, so you can choose before anything is downloaded. The download is where the full-resolution file is charged. A sensible order:

1. Look at the previews from step 3 and choose an id.
2. Call get_image with that id. It is free and returns the details, the quality tier, the download price in credits, the license, and whether a 4K upscale exists.
3. Call download_image. Leave rendition as original, or use upscaled_4k when get_image reports an upscale.

{
  "id": "<id of the image you chose>",
  "rendition": "original"
}

Response fields. A successful download returns data.url (a short-lived signed link to the full-resolution file), data.expires_at, data.owned, data.image_id, data.page_url (the image’s page on pix4less.com, which keeps working after the link expires), data.delivery (one sentence on how to hand the file over) and request_id. owned means access is authorized after this call; it does not mean the call was free.

An agent that can fetch URLs saves the file promptly and hosts it itself. Do not hotlink or log the signed URL, and do not send your API key to the storage host. Some chat assistants run in a sandbox that blocks the storage host; they cannot save the file, so they give you the link instead: it downloads in your browser, and data.page_url opens the image after the link has expired. Keep the image id, not the URL: you can request a fresh link whenever you need one. Images you already own are not charged again.

If nothing in the catalog fits, the agent can call generate_image. It is a separate, paid tool and only runs when the agent chooses it.

There is no separate MCP fee. Tools use the same credits as the API, and the prices below are read live from the price book when this page renders.

Quick search

1 credit / request

Thorough search

3 credits / request

New catalog download

1 credit / image (HD: 3 credits, 4K: 10 credits)

Previously purchased image

No duplicate download charge

Browsing, details, collections

Free

A search is charged only after a valid search returns at least one result; empty results, invalid input and service failures are not charged. Search and download are separate charges. Your agent can read the current numbers itself with get_pricing, which is free. Plans, top-ups and generation pricing.

Errors reach your agent as tool errors that start with the error code and HTTP status, followed by the message.

• 401, or the client says the server needs authentication. Sign in again from the client: /mcp in Claude Code, /mcp auth pix4less in Gemini CLI, codex mcp login pix4less in Codex, or Connect in Claude and Cursor. A sign-in ends when you disconnect the app in the dashboard or reset your password. With an API key instead, check that the header is Authorization: Bearer followed by your whole key.
• The sign-in page asks you to verify your email. A connected app spends credits, so an account created with email and password needs a confirmed address first. Use the link in the email, then connect again.
• 402, payment_required. The balance is below the price of the call. The error details give credits_required, balance and a topup_url.
• Empty results. The search matched nothing and was not charged. Use a broader description, drop hard filters such as size or format bounds, or set search_type to deep for detailed requests, which costs more.
• An expected image is missing: safe_search. It is on by default and leaves out images with a content warning (today, partial_nudity: sheer lingerie or swimwear that shows the body). Pass safe_search as false to include them; each such image lists its content_warnings so you can label or drop it yourself.
• 429, rate_limit_exceeded. You sent too many requests. Wait for the Retry-After period before trying again.
• 503, search_timeout or catalog_unavailable. The search did not finish and nothing was charged. Try again later.
• 403, download_unavailable. Downloads of that image are withheld, for example in a collection whose downloads are not offered. Nothing is charged.

More detail is in the error reference, and the MCP server overview lists every tool. Building a website instead? See Add stock images to a Next.js site.