Connect Images MCP

Images MCP gives your agent tools to search the Lightdrift image library, find similar images, and retrieve image details. This is the same connection available under Learn → Connect Images MCP in the dashboard.

Connection	Details
Server URL	`https://lightdrift.ai/mcp`
Transport	Streamable HTTP
Authentication	Sign in with Lightdrift, or use an API key
Pricing	1 credit per 10 results (minimum 1) per successful search or similar-image call; image details are free

Want your agent to look up API usage and documentation? Connect Docs MCP. You can install both servers in the same client.

Before you connect

Use a client that supports remote MCP over Streamable HTTP. For browser sign-in, it also needs OAuth support. Have your Lightdrift account ready, or create one when prompted. New users must agree to the Terms of Service and Privacy Policy during signup. Searches use your account’s monthly credits. The Free plan includes 500 free credits every month. Check your remaining credits in Billing.

If sign-in opens in an embedded browser and Google or passkey sign-in fails, open the sign-in link in your normal browser and complete authentication there.

Tools

Tool	What it does	Cost
`search_images`	Search with text, a reference image, or both, using the same filters as the REST API. Searching with an image requires a paid plan.	1 credit per 10 results, minimum 1
`find_similar_images`	More images like an asset you already have. Requires a paid plan.	1 credit per 10 results, minimum 1
`get_image`	File URLs, provenance, dimensions, and the rights answer for one asset.	Free

Search by image, image plus text search, and find_similar_images are paid plan features (Starter and above). On the Free plan they return a 403 paid_feature error with an upgrade link, and text searches return at most 10 results. See Plans and limits. Every search result carries the same rights object as the REST API. See Rights answers. Searches default to excluding AI-generated records (non-AI artwork can still appear), commercial-use licences, files at least 1000 px wide, and nsfw_max:0.2; pass one of these defaulted filters as null to opt out (see Defaults).

Search architecture and options

Images MCP uses the same Voyage index as the REST API: 1,852,370 captioned images from 17 sources. Icon packs are not included. Joint image-and-caption embeddings feed semantic and keyword retrieval, then rerank-3 ranks candidate captions. mode:auto is the default: text queries use caption reranking, image-only queries use image similarity, and image-plus-text queries blend joint-embedding similarity with caption text reranking. text forces caption reranking and requires text; none skips reranking while still using Voyage embeddings. search_images accepts optional query plus image_base64 (upload as base64 or a data URL) or image_url (public HTTPS). Supply text, one image, or both; never both image fields. JPEG, PNG and WebP still images up to 5 MiB and 20 megapixels are supported. Images are resized to a maximum 1024-pixel edge before embedding. Use search examples for JSON payloads. find_similar_images continues to accept an indexed asset ID. Similarity excludes the seed and does not use text reranking. A seed outside the index returns an error; no old-index fallback is used. Search responses include backend, ranking and timing fields. Reranker failure may return an explicit degraded result in retrieval order; this successful response uses credits. Failed searches are not charged. Repeated MCP calls use credits again, because each is a new search. get_image is free and may resolve a saved legacy asset even when that asset cannot be used as a current-index similarity seed. File URLs redirect to signed downloads. If a client still shows the old tool schema, reconnect or refresh its tool list. Respect Retry-After for availability and rate-limit errors; do not wait for a legacy GPU to warm up.

Choose your client

Codex
Claude Code
Cursor
Claude
Other

codex mcp add lightdrift --url https://lightdrift.ai/mcp
codex mcp login lightdrift

Complete sign-in in the browser, then return to Codex.With an API key instead, in ~/.codex/config.toml:

[mcp_servers.lightdrift]
url = "https://lightdrift.ai/mcp"
http_headers = { "X-API-Key" = "YOUR_LIGHTDRIFT_API_KEY" }

claude mcp add --transport http lightdrift https://lightdrift.ai/mcp

Then type /mcp inside Claude Code, pick lightdrift, and choose Authenticate. Your browser opens; sign in and you are connected.With an API key instead:

claude mcp add --transport http lightdrift https://lightdrift.ai/mcp --header "X-API-Key: YOUR_LIGHTDRIFT_API_KEY"

Add to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "lightdrift": {
      "url": "https://lightdrift.ai/mcp"
    }
  }
}

Open Cursor Settings, MCP, and click Connect next to lightdrift. Your browser opens to sign in.With an API key instead, add a headers object:

{
  "mcpServers": {
    "lightdrift": {
      "url": "https://lightdrift.ai/mcp",
      "headers": { "X-API-Key": "YOUR_LIGHTDRIFT_API_KEY" }
    }
  }
}

In Claude on the web or desktop, open Settings, Connectors, Add custom connector, and paste:

https://lightdrift.ai/mcp

Claude opens a sign-in window. Approve access and the tools appear in your chat. Custom connectors are sign-in only.

Use the server URL in your client’s remote MCP settings. For clients that use a mcpServers configuration, the entry looks like this:

{
  "mcpServers": {
    "lightdrift": {
      "url": "https://lightdrift.ai/mcp"
    }
  }
}

If the client can send custom headers, X-API-Key replaces the sign-in step.

Create a key in API keys, then use the header configuration shown for your client above. In other clients with custom header support, set X-API-Key to your key. Use either OAuth or an API key for a connection, not both. Keep keys out of shared project files and source control. Use your client’s private configuration or secret storage when available. API-key requests use the credits of the account that owns the key.

Check the connection

Open your client’s MCP tools list and look for search_images, find_similar_images, and get_image under lightdrift. If they are missing, reload the connection or restart the client after saving its configuration. Listing tools does not run an image search. The example below does: a successful search uses 1 credit.

First search

Once connected, ask for an image the way you would ask a person:

Find me a photo of a coastal lighthouse at dusk with room for a headline on the left, and tell me the attribution I need to include.

The agent calls search_images, reads rights.attribution from the top result, and hands you both.

Troubleshooting

What happened	What to do
The server is missing or no tools appear	Check the URL, enable the server in your client, and reload the connection. Confirm the client supports remote Streamable HTTP.
`401` or authentication required	Complete your client’s sign-in step again. For API keys, check the `X-API-Key` header and whether the key is still active.
`402` or `credits_exhausted`	Your monthly credits are used up. Upgrade in Billing or wait for the monthly reset. On Scale and Custom you can buy a credit pack.
`403` or `paid_feature`	Search by image and find similar require a paid plan. Upgrade in Billing.
`429` or rate limited	Wait before retrying and reduce simultaneous searches. Follow a retry delay if the response provides one.
Browser sign-in fails or loops	Open the sign-in link in your normal browser. If the client cannot complete OAuth, use an API key if it supports custom headers.
The tools only search documentation	You connected Docs MCP. Add `https://lightdrift.ai/mcp` as a separate server named `lightdrift`.
Search results are too restrictive	Searches default to real photos, commercial-use licenses, and a minimum width of 1000 px. Ask the agent to change the relevant filters; see search defaults.

Next steps

Read Plans and limits for plans, request allowances, and credit usage.
Read the search guide for filters and similar-image search.
Learn how to use license and attribution details.
Add Docs MCP so your agent can also look up Lightdrift usage.

Need to compare credentials or isolate a connection problem? Use the API and MCP authentication troubleshooting guide.

Get started

Learn

Account

Core concepts

Before you connect

Tools

Search architecture and options

Choose your client

Check the connection

First search

Troubleshooting

Next steps

Before you connect

Tools

Search architecture and options

Choose your client

Use an API key instead of sign-in

Check the connection

First search

Troubleshooting

Next steps