Skip to main content

Claude Desktop

Claude Desktop can point at a custom endpoint through its Configure Third-Party Interface setting. That setting takes one base URL and one API key, with no model configuration at all, so it works with any provider your LLM Registry entry serves: Anthropic, OpenAI, Gemini, Bedrock, or OpenRouter.

The setting lives behind Claude Desktop's Developer menu, which is hidden by default. Step 1 turns it on.

Which setup do you need?​

What you getUse it when
LLM Registry entryThe model, governedYou only need model access
Agent PersonaThe model and the persona's MCP toolsYou want Claude Desktop to use tools as well
note

A persona takes two pastes in Claude Desktop, in two different files. Configure Third-Party Interface wires up the model and has no MCP field at all, so the persona's tools are registered separately in claude_desktop_config.json. Follow the setup below for the model, then register the persona's tools.

Setup​

1. Enable the Developer menu​

The Developer menu doesn't appear in the menu bar until developer tools are allowed. Create the settings file that enables them:

echo '{ "allowDevTools": true }' > ~/Library/Application\ Support/Claude/developer_settings.json
caution

This command overwrites developer_settings.json. If you already have that file with other settings in it, open it in an editor instead and add "allowDevTools": true alongside what's already there.

2. Restart Claude Desktop​

Quit Claude Desktop completely and reopen it. A Developer menu now appears in the menu bar.

3. Open Configure Third-Party Interface​

Go to Developer → Configure Third-Party Interface, then set:

  • Connection to Gateway
  • Credential Kind to Static API Key

4. Enter the Gateway Base URL​

Pick the route you want.

https://<gateway-host>/llm/<url-prefix>
note

Unlike the Cursor setup, this URL takes no /api/v1/cursor suffix. Paste the endpoint URL exactly as the Connect flow shows it.

5. Enter the Gateway API Key, then save​

Claude Desktop has exactly one credential field, so what goes in it depends on your entry's credential mode. Pick the tab that matches.

The gateway holds the provider credential, so the field carries your Agent Access Key on its own:

<your-agent-access-key>

An AWS SigV4 (Bedrock) entry works the same way, since the gateway holds those credentials too.

Save the setting. Claude Desktop now routes its model calls through the gateway.

Register the persona's tools​

The steps above wire up the model half of the persona. This registers its tools, so Claude Desktop can call them.

Claude Desktop speaks MCP over stdio rather than HTTP, so the entry launches mcp-remote, a small bridge that forwards to a remote endpoint. It needs Node.js installed; if npx --version prints a version, you have it.

1. Open the config file​

Go to Settings → Developer → Edit Config. This opens claude_desktop_config.json in your default editor. The Developer tab is the one step 1 above enabled.

You can also open the file directly:

open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. Add the persona under mcpServers​

Add this entry alongside any servers already listed:

{
  "mcpServers": {
    "<persona-name>": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<gateway-host>/p/<persona-id>",
        "--header",
        "X-Agent-Key:${AGENT_KEY}"
      ],
      "env": {
        "AGENT_KEY": "<your-agent-access-key>"
      }
    }
  }
}
caution

No space after the colon in X-Agent-Key:${AGENT_KEY}. Claude Desktop splits arguments on whitespace before mcp-remote sees them, so X-Agent-Key: ${AGENT_KEY} arrives as two broken arguments and the header never reaches the gateway. This is the most common reason the server connects but every tool call returns an authentication error.

What each part does:

  • --header and its value are separate array entries. Combining them into one string does not work.
  • env holds the real key, and ${AGENT_KEY} in the argument refers to it. Keeping the secret in env is what lets you share the rest of the file safely.
  • The URL is the persona root, /p/<persona-id> — no /llm/... path. That path belongs to the model route in step 4 above, and the two are different endpoints on the same persona.

3. Save and restart​

Save the file, then quit Claude Desktop completely and reopen it. Closing the window is not enough; the config is read at launch.

Confirm under Settings → Developer — the persona now appears in the list, and its tools are available in a new conversation.

Where to find each value​

PlaceholderWhere to find it
<gateway-host>Host from the entry's Overview tab, for example gw.aigateway.example.com
<url-prefix>The URL prefix field on the entry's Overview tab
<persona-id>The persona's ID on the Agent Persona page
<registry-entry-id>The entry's ID in the entry's URL
<persona-name>Any short label you want to give the tools socket locally
<your-agent-access-key>Generate from the entry's Agent Access Keys step, or the persona's Connect flow. Plaintext is shown once.
<your-provider-key>Your own provider API key, needed only in passthrough mode

The entry's Connect flow shows the Claude Desktop steps with the real base URL and key already filled in, ready to copy.

Tips​

  • The Developer menu survives updates, the file may not. If the menu disappears after a Claude Desktop update, re-run the step 1 command and restart.
  • Restart after step 1, not just a window close. Quit Claude Desktop fully. Closing the window leaves it running, and the menu won't appear.
  • Check the two dropdowns if calls fail immediately. Connection must be Gateway and Credential Kind must be Static API Key. Any other combination sends a request shape the gateway endpoint doesn't expect.
  • Two colons, no spaces. In the combined form, :: is the separator. A space on either side becomes part of the credential, and authentication fails.
  • npx not found? mcp-remote needs Node.js. Install it from nodejs.org, then restart Claude Desktop so it picks up the new PATH.
  • Tools missing after an edit? Claude Desktop reads claude_desktop_config.json only at launch, and invalid JSON is skipped silently. Check the file parses, then fully quit and reopen.
Last updated on