First run checks before the config file goes near Claude Desktop
Pointing Claude Desktop at a custom endpoint is one line of configuration, but that line sits on top of everything else the app assumes about the network and the credential. Do the boring checks first, because every one of them produces an error that looks like a broken endpoint when it is really a local problem.
Start with the app itself and the machine it runs on. Make sure Claude Desktop is on a recent build, that it is allowed through the firewall and any corporate proxy, and that no TLS inspection tool is rewriting traffic. On macOS and Windows, GUI apps do not always inherit the shell profile, so an ANTHROPIC_BASE_URL, HTTP_PROXY or HTTPS_PROXY variable you set for a terminal tool may or may not reach Claude Desktop. Check the app's own logs or diagnostic panel instead of assuming.
- Confirm the app can reach the general internet before you aim it at any endpoint.
- Confirm no old proxy or VPN setting is redirecting the request.
- Confirm the credential you plan to use is an API key, not a browser session or an account login.
- Restart the app after any config edit so the change is actually picked up.
Once those are clean, the endpoint field becomes a single variable you can reason about, and the rest of this checklist gets much shorter.
Side by side: the default account route and a custom endpoint route
Claude Desktop ships with one obvious path: sign in, use the Claude family of models, and let billing flow through that account. That route is simple and it is the right default if you only ever want Claude models and never want to touch configuration.
The custom endpoint route changes three things at once. You supply the base URL, you supply an API key from that endpoint, and the model list becomes whatever that endpoint exposes. In exchange you get control over which models back the chat and where the token spend is recorded.
- Model range: the default route gives you the Claude family, including Claude Sonnet 5.5 and Claude Haiku 4.5. A custom endpoint can expose those plus other providers, depending on what the relay carries.
- Credential: the default route keys off your account login, while a custom endpoint keys off a single API key you can rotate or revoke.
- Billing: the default route follows the account, while a relay such as SwiftRelay bills per token with a pay-as-you-go balance.
- Portability: a custom endpoint configuration can be copied to Claude Code, Codex, Gemini CLI or any OpenAI-compatible SDK with small edits.
If you only chat in Claude Desktop and nothing else, the default route is fine. The moment you want the same key to work in a terminal agent or an SDK script, the custom endpoint route earns its complexity.
Endpoint shape: bare host, /v1, and the errors that follow
Most custom endpoint failures come from the URL shape rather than the network. SwiftRelay's API host is https://api.fastapirelay.com, and the path suffix depends on the client you configure. Claude Code and Gemini CLI take the bare host. OpenAI-compatible SDKs add /v1. Claude Desktop's endpoint field has its own expectation, so follow the exact form the config template shows instead of pasting a URL that worked somewhere else.
The good news is that wrong shapes fail loudly. Read the error before you rewrite anything, because the message usually names the problem.
- A 401 or an authentication error means the key is wrong, expired, or missing from the header.
- A 404 or a route not found error means the path suffix does not match what the client appended.
- A model not found error means the URL is right and the model string is wrong.
- A body or content type error often means the client is speaking one protocol variant while the endpoint expects another.
Change one thing at a time. If you move from a bare host to a host with a suffix and also change the model name in the same edit, you lose the ability to tell which change fixed the run.
Credentials and model names are the two things that must match exactly
After the URL is settled, the remaining failures are naming and scope. An API key is scoped to an account or project on the relay side, so make sure the key you paste belongs to the balance you intend to spend from. Keys are usually passed as a bearer token in the authorization header, and Claude Desktop handles that header for you once the key is in the right field.
Model names are the second trap. Model identifiers are case sensitive strings that must match the relay's catalogue exactly. Claude Sonnet 5.5 and Claude Haiku 4.5 are distinct entries with distinct identifiers, and a trailing space or a guessed version number is enough to produce a not found response.
- Copy model identifiers from the provider's catalogue page rather than typing them.
- Trim whitespace from the key and the model string.
- Keep the key out of shared screenshots, config files in public repos, and chat logs.
- Test the endpoint with a short prompt first, then load a long context.
- Save a working config before you experiment with a second model.
These two checks cover most support threads, and they take a few minutes before a green light run.
One key, many models, and billing that follows your tokens
A relay earns its place in Claude Desktop when you want a single credential to reach more than one family of models. SwiftRelay carries Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen, Grok and others behind one API host, and it works with Claude Code, Codex, Gemini CLI and any OpenAI-compatible SDK. That means the config you fix today for Claude Desktop is close to the config you reuse in a terminal agent tomorrow.
Billing is pay-as-you-go and measured per token, so the balance reflects what you actually send and receive instead of a fixed allowance. New accounts receive a small gift credit, which is useful for the first run, and inviting friends earns 14% of their top-ups. If this is the route you want, sign up for SwiftRelay and keep the API key beside the Claude Desktop config for the next section.
- Use the bare host where the client expects it, and add the SDK suffix only where the client requires it.
- Pick a fast model for quick config tests and a larger model once the endpoint is confirmed.
- Reuse the same key across tools to keep spend visible in one place.
Recommendation: the route that wins for a custom endpoint
Put the checks in order and the decision becomes clear. If you want Claude Desktop to stay exactly as it ships and you never leave the Claude family, the default account route is the shorter lap and there is no reason to add configuration.
If you want one credential that survives across Claude Desktop, a terminal agent and SDK scripts, go with the custom endpoint route and use SwiftRelay as the endpoint. The bare host and suffix rules are the only moving parts, the model catalogue includes current entries such as Claude Sonnet 5.5, and the per-token pay-as-you-go balance keeps the spend honest.
Our recommendation is the custom endpoint route for anyone running more than one tool, with the local network, credential and model name checks done in that order before the first real prompt. Do those three checks, confirm one short run, and the green light is earned rather than hoped for.