Find Unsplash photos from your AI assistant, with credits included.

claude.ai

A custom connector works in claude.ai on the web and in the desktop and mobile apps.

1. Go to claude.ai/customize/connectors and choose Add custom connector.
2. Name: Unsplash
3. URL: https://unsplash.mocra.com/mcp
4. Authentication: No sign-in
5. Under Request headers, add a header. Choose the name x-api-key from the list. Value: <your-unsplash-access-key>, with no prefix.
6. Save. Then enable the connector in a chat from the tools menu.

Don't use X-Unsplash-Access-Key here. claude.ai only accepts header names that Anthropic has approved. If you try this name, claude.ai says it "isn't approved" and won't add the connector.

If claude.ai shows "Connection issue"

You may also see "Couldn't connect to the server. Check that the URL points to a valid MCP server." The cause may be the header and not the URL. Check that the header value is your full key. If you used Authorization, check that the value includes the Bearer prefix.

You can't view a header value after you save it, and the connector menu only offers Remove. To fix a value, remove the connector and add it again.

These steps were checked on a Max plan. Other plans may differ. On a Team or Enterprise plan, an owner may need to add custom connectors in organisation settings first. Anthropic's help article

Claude Code

In your terminal

Set your key in your shell, then add the server to your user config:

export UNSPLASH_ACCESS_KEY=<your-unsplash-access-key>

claude mcp add --transport http --scope user unsplash https://unsplash.mocra.com/mcp \
  --header "X-Unsplash-Access-Key: $UNSPLASH_ACCESS_KEY"

Run /mcp in Claude Code and check that unsplash has a check mark.

In a project, or on Claude Code on the web

Commit this .mcp.json to the root of the repository. Claude Code fills in the variable when it runs, so your key stays out of git.

{
  "mcpServers": {
    "unsplash": {
      "type": "http",
      "url": "https://unsplash.mocra.com/mcp",
      "headers": { "X-Unsplash-Access-Key": "${UNSPLASH_ACCESS_KEY}" }
    }
  }
}

On your own computer, set UNSPLASH_ACCESS_KEY in your shell. For Claude Code on the web:

1. Open the cloud environment menu in the session's title bar and choose Edit.
2. Add the environment variable UNSPLASH_ACCESS_KEY with your key as its value.
3. Under Network access, choose a broader access level, or add unsplash.mocra.com under Allowed domains.
4. Start a new session. Claude Code reads these settings when a session starts.

If you added the claude.ai connector, it is also available in Claude Code on the web sessions. Claude Code MCP docs

ChatGPT

OpenAI's docs list three authentication choices for a custom MCP server: OAuth, No authentication, and OAuth or no authentication. They describe no field for a custom header. Their plugin authentication docs also say that ChatGPT can't "present custom API keys". This server has no OAuth sign-in, so there are no working steps to show here.

Don't put your key in the connector's URL. A URL can leak through logs and screenshots.

What you can use instead

OpenAI's docs say the ChatGPT desktop app shares its MCP configuration with Codex, so the Codex setup may work there. ChatGPT on the web doesn't read that file.

Based on OpenAI's docs, checked November 2026. Not tested in ChatGPT itself. Add a custom MCP server · Plugin authentication · Codex MCP configuration

Codex

1. Add this to ~/.codex/config.toml:

   [mcp_servers.unsplash]
   url = "https://unsplash.mocra.com/mcp"
   env_http_headers = { "X-Unsplash-Access-Key" = "UNSPLASH_ACCESS_KEY" }

2. Set the variable where Codex can read it. Codex sends its value in the X-Unsplash-Access-Key header. The config names the variable, so your key stays out of the file.

   export UNSPLASH_ACCESS_KEY=<your-unsplash-access-key>

3. Run codex mcp list, or /mcp inside Codex, and check that unsplash is listed.

The Codex IDE extension uses the same file. Open its gear menu, select MCP servers, then select Restart extension. Codex MCP docs

Cursor

1. Add this to ~/.cursor/mcp.json for all projects, or to .cursor/mcp.json for one project:

   {
     "mcpServers": {
       "unsplash": {
         "url": "https://unsplash.mocra.com/mcp",
         "headers": { "X-Unsplash-Access-Key": "${env:UNSPLASH_ACCESS_KEY}" }
       }
     }
   }

2. Set UNSPLASH_ACCESS_KEY in your shell profile or system environment, then restart Cursor.
3. In the Customize sidebar, check that unsplash is listed and turned on.

If it doesn't connect, open the Output panel and choose MCP Logs. Cursor MCP docs

VS Code

1. Add this to .vscode/mcp.json in your workspace:

   {
     "inputs": [
       {
         "type": "promptString",
         "id": "unsplash-key",
         "description": "Unsplash access key",
         "password": true
       }
     ],
     "servers": {
       "unsplash": {
         "type": "http",
         "url": "https://unsplash.mocra.com/mcp",
         "headers": { "X-Unsplash-Access-Key": "${input:unsplash-key}" }
       }
     }
   }

2. Open the Command Palette, run MCP: List Servers and start unsplash.
3. Enter your key when VS Code asks for it. VS Code stores it securely, so it stays out of this file.

VS Code doesn't forward servers that use input variables to Copilot harness sessions. VS Code MCP configuration docs

Other clients

Any client that supports Streamable HTTP and custom headers can connect with these settings:

• URL: https://unsplash.mocra.com/mcp
• Header: X-Unsplash-Access-Key: <your-unsplash-access-key>. The value is just the key.
• Or this header, whose value is also just the key: X-API-Key: <your-unsplash-access-key>
• Or this header, which needs a prefix: Authorization: Bearer <your-unsplash-access-key> or Authorization: Client-ID <your-unsplash-access-key>

A client that can't send a custom header can't use the hosted server.

Check your key from a terminal

This lists the server's tools. It sends your key, but makes no call to Unsplash, so it doesn't check that Unsplash accepts the key.

curl https://unsplash.mocra.com/mcp \
  -H "X-Unsplash-Access-Key: $UNSPLASH_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Run it on your own computer

Desktop clients can run the server locally over stdio instead. You need Bun and a copy of the source.

{
  "mcpServers": {
    "unsplash": {
      "command": "bun",
      "args": ["/path/to/unsplash-mcp-server/src/stdio.ts"],
      "env": { "UNSPLASH_ACCESS_KEY": "<your-unsplash-access-key>" }
    }
  }
}