Troubleshoot Lightdrift API and MCP authentication

If you are wiring image search into a presentation builder, website agent, or content pipeline, first identify which Lightdrift endpoint your application actually uses. A browser sign-in, an API key, and access to public documentation serve different purposes.

Match the endpoint to the credential

Connection	Endpoint	Documented authentication
REST API	`https://api.lightdrift.ai/v1/search`	API key in the `X-API-Key` request header.
Images MCP	`https://lightdrift.ai/mcp`	Lightdrift browser sign-in (OAuth), or `X-API-Key` if your client supports custom headers. Choose one method per connection.
Docs MCP	`https://docs.lightdrift.ai/mcp`	None. Public documentation requires no account, API key, or OAuth login.

Both MCP servers use Streamable HTTP. Name them separately, such as lightdrift and lightdrift-docs. An Images MCP OAuth session does not configure the API key used by a standalone Python script.

Find the symptom, then check the configuration

Symptom	Next check or fix
Your REST script has no API key available	Supply `LIGHTDRIFT_API_KEY` to the process that runs the script, or use the hidden prompt below. A variable set in another terminal or a developer laptop may not be available to your deployed worker. Restart that process after changing its secret configuration.
An Images MCP connection reports authentication required or `401`	Complete the client’s sign-in again. If using a key, check that it is active and sent as `X-API-Key`; use the client-specific setup.
Images MCP browser sign-in fails or loops	Open the sign-in link in your normal browser. Confirm your client supports OAuth; if it cannot complete OAuth, use a key only if it supports custom headers.
No image tools appear	Check the Images MCP URL, enable the server, and reload the connection or restart the client. Confirm remote Streamable HTTP support. Look for `search_images`, `find_similar_images`, and `get_image`.
The agent returns documentation instead of images	Add Images MCP as a separate server. Docs MCP searches documentation; it does not search the image library.
Docs MCP asks for a Lightdrift key or sign-in	Check for the exact Docs MCP URL above and remove image-server authentication headers from that connection. No Lightdrift login step is needed.
Images MCP reports `402` or `credits_exhausted`	The account’s monthly credits are used up. Check the billing page to upgrade, or wait for the monthly reset. A key uses its owning account’s credits; changing connection syntax does not add credits.
Images MCP reports `403` or `paid_feature`	Search by image and find similar require a paid plan. Upgrade in the billing page. This is not an authentication problem.
Images MCP reports `429` or a rate limit	Reduce concurrent searches and respect a returned retry delay. Check plans and limits; do not rotate credentials to work around a limit.

The numeric symptoms above are documented in the Images MCP troubleshooting reference. For a REST failure, inspect the actual HTTP status and response in your private development environment rather than assuming every failure is authentication. Empty results or a degraded ranking response also do not, by themselves, identify a credential problem. Create or manage a key in API keys. Keep it in your backend secret manager or private client configuration. Do not put it in browser-delivered code, a shared project configuration, a public repository, screenshots, or support messages. Environment variables are one way to pass a secret to a process; they are not a reason to dump that process’s environment into logs. For MCP, follow the canonical Images MCP setup. Placeholder keys in configuration examples must be replaced only in private storage. If a key has been exposed, revoke it in the dashboard and update the affected clients with a replacement.

Verify with one REST request

First check your account’s remaining credits in Billing. This example sends one search, without retries, which uses 1 credit if it succeeds. See Plans and limits for how credits are counted. Listing MCP tools instead checks tool availability without running a paid image search, but does not prove a search will succeed. Save this as check_lightdrift.py and run python3 check_lightdrift.py in a terminal. It uses only the Python standard library, reads LIGHTDRIFT_API_KEY if supplied, and otherwise prompts without echoing the key. It prints no credential, request headers, or response body.

import getpass
import json
import os
import urllib.error
import urllib.request

key = os.environ.get("LIGHTDRIFT_API_KEY") or getpass.getpass("Lightdrift API key: ")
if not key.strip():
    raise SystemExit("No API key supplied; no request sent.")

payload = {
    "query": "coastal lighthouse at dusk with room for a headline",
    "k": 1,
    "experiment": "lig129_auth_check_v1",
}
request = urllib.request.Request(
    "https://api.lightdrift.ai/v1/search",
    data=json.dumps(payload).encode("utf-8"),
    headers={"X-API-Key": key, "Content-Type": "application/json"},
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=60) as response:
        result = json.load(response)
        print("HTTP", response.status)
        print("Query ID:", result.get("query_id"))
        print("Candidates:", len(result.get("results", [])))
except urllib.error.HTTPError as error:
    print("HTTP", error.code, "— check your private response and account settings.")
except (urllib.error.URLError, TimeoutError):
    print("Connection failed or timed out; completion is unknown. Check usage before retrying.")

A successful response with a query ID verifies this REST request, not your separate MCP connection or future requests. Zero candidates is not proof of authentication failure. After an uncertain timeout, check account usage before repeating the search: a repeat uses credits again.

Next steps

Return to the REST quickstart, Images MCP setup, or Docs MCP setup for the connection you use. Before placing any returned image in a product, check its source page, subject, license conditions, and required attribution. Preserve source links and credits through export. Returned rights metadata is a source declaration, not clearance for every use; see Rights answers. Create an account to try your first request.

Get started

Learn

Account

Core concepts

Troubleshoot Lightdrift API and MCP authentication

Match the endpoint to the credential

Find the symptom, then check the configuration

Verify with one REST request

Next steps

Match the endpoint to the credential

Find the symptom, then check the configuration

Configure credentials without sharing them

Verify with one REST request

Next steps