LLM Registry: Client Setup Guides
The LLM Registry lets your team point any AI runtime (Claude Code, Claude Desktop, Cursor, a Python SDK) at the Cequence AI Gateway instead of calling OpenAI, Anthropic, or Google directly. The gateway takes care of authentication, provider credentials, usage attribution, and enforcement, so the runtime doesn't need to know which provider is on the other side.
Because the gateway speaks the providers' own API formats, any client that already works with OpenAI, Anthropic, or Gemini works here. You're changing the endpoint it points at, not the way it talks. The guides below walk through the most common runtimes step by step.
Quick start
Pick your runtime from the sidebar, then choose the provider and credential mode inside the guide:
- Claude Code: LLM Registry entry or Agent Persona, across all three credential modes, plus Claude Pro/Max plans
- Claude Desktop: LLM Registry entry or Agent Persona, through Configure Third-Party Interface
- Codex CLI: LLM Registry entry or Agent Persona, both wired from
~/.codex/config.toml - Gemini CLI: LLM Registry entry or Agent Persona, with the persona's MCP tools attached
- Cursor IDE: LLM Registry entry or Agent Persona, from Cursor's model settings
- Anthropic Python SDK: LLM Registry entry or Agent Persona, using Anthropic's MCP connector for tools
- OpenAI Python SDK: LLM Registry entry or Agent Persona, using the Responses API's MCP tool
- Google ADK: LLM Registry entry or Agent Persona, for Gemini agents in Python
Want to see a full end-to-end example first? Code Review Agent with the Anthropic Python SDK walks through a persona with a GitLab MCP tool and a code-review skill attached, driven from the Anthropic SDK.
Using a runtime that isn't listed yet? It will almost certainly work. Set its base URL to your LLM Registry endpoint and its API key to your Agent Access Key. If something doesn't behave the way you expect, reach out to your Cequence contact and we'll help you get it configured.
Two ways to connect
Every runtime guide is organised around the same two routes, because a gateway endpoint can be reached either on its own or through an Agent Persona.
| Route | Endpoint | What the runtime gets |
|---|---|---|
| LLM Registry entry | /llm/<url-prefix> | The model, governed by the entry's policies |
| Agent Persona | /p/<persona-id>/llm/<registry-entry-id> | The model and the persona's MCP tools, under the persona's policies |
The Agent Persona route is the fuller setup and the one most teams end up on: a single Agent Access Key authenticates both the model calls and the tool calls, so the agent reaches its tools and its model through one governed surface.
Both routes use the same credential modes and the same credential placement. Only the base URL changes, plus the extra command that registers the persona's tools socket.
Two separate settings decide how a call authenticates, and they are easy to confuse:
- The entry's credential mode — API Key, AWS SigV4, or Passthrough. This decides which credentials your runtime sends, and it is what nearly all of the configuration in these guides depends on. Every guide switches on it.
- The persona's Inbound Authentication method — Interactive or Passthrough. This decides how the persona identifies the caller. Either way an Agent Access Key is issued, and it changes almost nothing in a runtime's configuration, least of all in the SDKs.
One consequence is worth knowing before you start: the Agent Persona route always requires an Agent Access Key. An entry that needs no key on its own still needs one when it is reached through a persona. So the three credential modes below apply in full to the LLM Registry entry route, while the persona route uses the first two.
Terminology
The same few words show up on every guide. If they're new to you, read this once and the rest of the section is straightforward.
Provider. The upstream LLM service the entry points at: OpenAI, Anthropic, OpenRouter, Google Gemini, Amazon Bedrock, and so on. Set when the entry is created.
Credential mode. How the provider credential is handled. This is a field on the entry's Provider Credential panel, and it has three settings:
- API Key. You upload the provider's API key once, and the gateway stores it. Your runtime never sees it and sends only its Agent Access Key. The Connect flow calls this a gateway-managed credential.
- AWS SigV4 (Bedrock). The Bedrock equivalent. You supply AWS credentials, and the gateway signs each outbound call with them.
- Passthrough. Shown in full as Passthrough (agent supplies its own key). The gateway holds no provider credential, and your runtime supplies the provider key at call time. Useful for personal accounts, subscription plans, or short-lived tokens.
Agent Access Key. The gateway's own credential, generated on the entry's Connect flow. It identifies the caller for enforcement and audit. It's generated once and revealed only at creation time, so copy it somewhere safe.
Agent Persona. A tenant-defined scope that bundles a set of allowed tools and, optionally, LLM access under one endpoint. When the entry is reached via an Agent Persona, the same Agent Access Key covers both the persona's tools and its LLM calls.
Which credentials does my entry need?
This is the question every setup guide depends on, so it's worth settling once.
An entry in API Key or AWS SigV4 mode always needs an Agent Access Key, because there's nothing else identifying you. A Passthrough entry may or may not, depending on one setting: Require an agent access key, the toggle on the entry's Provider Credential panel.
| Credential mode | Require an agent access key | What your client sends |
|---|---|---|
| API Key, or AWS SigV4 | Always on, and can't be turned off | Agent Access Key only |
| Passthrough | On | Your provider key and your Agent Access Key |
| Passthrough | Off | Your provider key only |
This table describes the LLM Registry entry route, /llm/<url-prefix>. On the Agent Persona route the last row never applies: an Agent Access Key is always required there, whatever this toggle says.
New passthrough entries are created with this requirement on. Note the hint the portal shows while it's on and no key exists yet: until you attach a key from the Connect steps, the endpoint rejects every call rather than serving it unprotected.
A passthrough entry can also start requiring a key without anyone touching this toggle. If an Agent Persona is granted a model from the entry, that grant contributes a key, and the entry begins expecting one. If calls that used to work suddenly return an authentication error, check this panel first.
Where the Agent Access Key goes
When a passthrough entry requires an Agent Access Key, the key reaches the gateway in the X-Agent-Key header. The gateway deliberately does not go looking for it in the Authorization, x-api-key, or x-goog-api-key headers, because those belong to your provider credential. Reading a key from them is what used to make passthrough entries fail with a misleading "invalid API key."
Most clients can send a custom header, and their guides show exactly how:
| Client | How it sends X-Agent-Key |
|---|---|
| Claude Code | ANTHROPIC_CUSTOM_HEADERS |
| Codex CLI | http_headers in config.toml |
| Gemini CLI | GEMINI_CLI_CUSTOM_HEADERS |
| Anthropic Python SDK | default_headers on the client |
| OpenAI Python SDK | default_headers on the client |
| Google ADK | headers in types.HttpOptions, inside client_kwargs |
Clients with only one credential field
Cursor, Claude Desktop, Continue, and Aider each expose a single API-key field, which isn't enough for a passthrough entry that needs two credentials. For these, combine both into that one field, provider key first, separated by two colons:
<your-provider-key>::<your-agent-access-key>
The gateway splits the value back apart before authenticating. Provider key first matters, because some clients check that a key starts with sk- and only this order survives that check.
This combined form isn't limited to those four clients. Anything that reaches the gateway can use it, including the Python SDKs, so it's a useful fallback whenever setting a custom header is awkward. The header remains the clearer option when a client supports one, since each credential stays in its own place.
Either way, this applies only to passthrough entries that require an Agent Access Key. On an API Key or AWS SigV4 entry, the single field carries the Agent Access Key by itself, exactly as before.
What you give up by turning it off
Leaving Require an agent access key off lets any caller through with just a provider key. It also means the gateway can't tell those callers apart, so three things stop applying:
- Team access restrictions on the entry
- Per-user attribution in activity and audit records
- Per-user token budgets. Without an identity, every anonymous caller shares one budget rather than each holding their own.
If you rely on any of these, keep the requirement on.
Tips
- Start from the Connect flow. Each entry's Connect flow shows the endpoint URL and ready-made configuration for common runtimes, with the right credentials already in the right places. Copying from there is faster and less error-prone than assembling anything by hand.
- Regenerate a lost key. Agent Access Key plaintext is shown only once. If you lose it, generate a new one from the entry's Connect flow. There's no way to recover the original.
- One key per attach point. An Agent Access Key attaches to either an LLM Registry entry or an Agent Persona, never both. Generate a separate key for each surface a runtime reaches.
- An authentication error isn't always about your key. On a passthrough entry, check whether the entry requires an Agent Access Key, and whether your client is sending it in the right place, before assuming the key itself is wrong.
Cequence AI Gateway