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	$0.02 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 workspace’s available credit. Check your balance in the dashboard.

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`	Natural-language search over the index, with the same filters as the REST API.	$0.02 per successful call
`find_similar_images`	More images like an asset you already have.	$0.02 per successful call
`get_image`	File URLs, provenance, dimensions, and the rights answer for one asset.	Free

Every search result carries the same rights object as the REST API. See Rights answers. Searches default to real photographs, commercial-use licences, and files at least 1000 px wide; pass a filter as null to opt out (see Defaults).

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 credit of the workspace 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 a paid image search. The example below does: a successful search costs $0.02.

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 insufficient credit	Check the workspace balance and add credit.
`429` or rate limited	Wait before retrying and reduce simultaneous searches. Follow a retry delay if the response provides one.
`503` with `gpu_warming`	The search service is starting after being idle. This failed call is not charged. Wait about 30 seconds and retry; startup can take longer.
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 upgrades, 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.

Get started

Learn

Account

Core concepts

Before you connect

Tools

Choose your client

Check the connection

First search

Troubleshooting

Next steps

​Before you connect

​Tools

​Choose your client

​Use an API key instead of sign-in

​Check the connection

​First search

​Troubleshooting

​Next steps

Before you connect

Tools

Choose your client

Use an API key instead of sign-in

Check the connection

First search

Troubleshooting

Next steps