> ## 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 Images MCP
> Connect your agent to image search, sign in to Lightdrift, and find images with license and attribution details.
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](/guides/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](https://lightdrift.ai/dashboard/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` | 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)).
## Choose your client
```bash theme={null}
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`:
```toml theme={null}
[mcp_servers.lightdrift]
url = "https://lightdrift.ai/mcp"
http_headers = { "X-API-Key" = "YOUR_LIGHTDRIFT_API_KEY" }
```
```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.
Use the server URL in your client’s remote MCP settings. For clients that use a `mcpServers` configuration, the entry looks like this:
```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.
## Use an API key instead of sign-in
Create a key in [API keys](https://lightdrift.ai/dashboard/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](https://lightdrift.ai/dashboard/billing). |
| `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](/guides/search#defaults-you-get-without-asking). |
## Next steps
* Read [Plans and limits](/guides/plans-and-limits) for upgrades, request allowances, and credit usage.
* Read the [search guide](/guides/search) for filters and similar-image search.
* Learn how to use [license and attribution details](/guides/rights).
* Add [Docs MCP](/guides/docs-mcp) so your agent can also look up Lightdrift usage.