> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightdrift.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect with MCP
> One server URL. Your agent signs in, then searches the image index directly.
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](https://lightdrift.ai/dashboard/api-keys).
## 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](/guides/rights). 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](/guides/search#defaults-you-get-without-asking)).
## Set up your client
```bash theme={null}
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:
```bash theme={null}
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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.
```bash theme={null}
codex mcp add lightdrift --url https://lightdrift.ai/mcp
codex mcp login lightdrift
```
With an API key instead, in `~/.codex/config.toml`:
```toml theme={null}
[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:
```json theme={null}
{
"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:
```text theme={null}
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](https://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](mailto:hello@lightdrift.ai) 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: ` on every request. The server verifies the key and charges the key's workspace, the same as the REST API. Never send both.