Connect with MCP

Lightdrift ships a hosted MCP server at:

https://lightdrift.ai/mcp

It speaks streamable HTTP and standard OAuth. Add it to any MCP client, complete sign-in in the browser when the client asks, and the tools appear. Sign-in creates an account if you don’t have one, with free credit to start.

Sign-in opens in a browser. If your tool opens it inside an embedded or in-app browser, copy the link into your normal browser. Only email and password work inside embedded browsers; Google and passkey-based sign-ins such as GitHub two-factor fail there.

Prefer not to open a browser, or running on a server? Send an API key in an X-API-Key header instead. Keys are created in the dashboard.

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).

Set up your client

Claude Code
Cursor
Claude
Codex
Other clients

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.

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

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" }

Any client that supports remote MCP servers over streamable HTTP works:

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

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

Let the agent do it

Paste this into a coding agent and it connects the server and proves it works:

Connect the Lightdrift image search MCP to this environment.

Server URL: https://lightdrift.ai/mcp (streamable HTTP, OAuth or an X-API-Key header).
Add it the way this client adds remote MCP servers, then complete sign-in if prompted.
If sign-in opens inside an embedded or in-app browser, do not sign in there: open the link in the user's normal browser. Only email and password work inside embedded browsers.

Then call the search_images tool with the query "coastal lighthouse at dusk, room for a headline on the left"
and show me the top result's title, file URL, and rights.attribution.

No account yet? Sign-in creates one, free credit included. Docs: https://docs.lightdrift.ai/guides/mcp

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

You see	Cause	Fix
`401` or “Authentication is required”	The client never completed sign-in, or the `X-API-Key` header is wrong.	Re-run the client’s authenticate step, or create a fresh key in the dashboard and paste it exactly.
”Lightdrift request failed (402)“	The workspace has no credit.	Add credit at lightdrift.ai/dashboard/billing.
”Lightdrift request failed (429)“	The account’s per-minute or per-day limit was hit. Promo accounts allow 30 searches a minute and 2 at a time.	Wait for the window to reset, or purchase credit to move to a higher tier.
`503` with `gpu_warming`	The GPU was idle for over an hour and is restoring. The call is not charged.	Retry in about 30 seconds.
Google shows “Something went wrong”, or a passkey fails during sign-in	The sign-in opened in an embedded or in-app browser. Google refuses those and passkey prompts cannot complete there.	Open the sign-in link in your normal browser. Email and password is the only method that works inside an embedded browser.
`403` from `clerk.lightdrift.ai/oauth/register`	Only seen with Python’s default user agent, which the auth provider’s edge rejects. Node clients and browsers pass.	Set a `User-Agent` header on the registration request.
Sign-in loops or the client reports no registration endpoint	The client relies on OAuth dynamic client registration.	Use the `X-API-Key` header form for that client and tell us which client it was.

How authentication works

Sign-in (OAuth): the client discovers https://lightdrift.ai/.well-known/oauth-protected-resource/mcp, identifies itself (by client metadata document, or dynamic registration for older clients), and sends you to sign in. Signing in creates the account if needed; that account starts with $1 of credit and gets$ 9 more when a card is added. Tokens are scoped to openid profile email; the server resolves them to your workspace and charges its credit.
API key: the client sends X-API-Key: <key> on every request. The server verifies the key and charges the key’s workspace, the same as the REST API. Never send both.

Get started

Core concepts

Tools

Set up your client

Let the agent do it

First search

Troubleshooting

How authentication works

​Tools

​Set up your client

​Let the agent do it

​First search

​Troubleshooting

​How authentication works

Tools

Set up your client

Let the agent do it

First search

Troubleshooting

How authentication works