Skip to main content

Claude Code

Claude Code is Anthropic's terminal coding agent. It reads its endpoint and credential from environment variables, so pointing it at the Cequence AI Gateway is a matter of exporting the right values before you start it. There's no config file to edit.

Which setup do you need?​

There are two ways to reach a model through the gateway, and they differ in what else comes with it.

What you getUse it when
LLM Registry entryThe model, governedYou only need model access
Agent PersonaThe model and the persona's MCP tools, under one set of policiesYou want the agent to use tools as well as a model

The Agent Persona route is the fuller setup: one Agent Access Key authenticates both the model calls and the tool calls, and both run under the persona's guardrails.

Either way, which credentials you send depends on the entry's credential mode. If you haven't read which credentials your entry needs, start there.

Connect to an LLM Registry entry​

Pick the credential mode on the entry's Provider Credential panel.

The gateway stores the Anthropic credential, so Claude Code sends only its Agent Access Key.

export ANTHROPIC_BASE_URL="https://<gateway-host>/llm/<url-prefix>"
export ANTHROPIC_API_KEY="<your-agent-access-key>"
export ANTHROPIC_MODEL="<model-id>"

ANTHROPIC_API_KEY is free on this mode, so the Agent Access Key travels there. Claude Code sends it as x-api-key, which the gateway accepts. The gateway then attaches the stored Anthropic credential on the outbound side.

Restart Claude Code, or open a new terminal, so it picks up the new environment.

Connect through an Agent Persona​

An Agent Persona bundles a set of MCP tools and, optionally, LLM access under one endpoint. Wiring Claude Code to it takes two commands, because there are two sockets:

  • The tools socket, at https://<gateway-host>/p/<persona-id>, registered with claude mcp add.
  • The model route, at https://<gateway-host>/p/<persona-id>/llm/<registry-entry-id>, set through the same environment variables as above.

One Agent Access Key covers both. You don't mint a separate key per socket.

The credential mode below is still the LLM Registry entry's, and it changes only the model half. The persona's own Inbound Authentication method (Interactive or Passthrough) does not change these commands.

note

Two separate settings are in play here, and only one of them changes the code below.

  • The entry's credential mode — API Key or Passthrough — decides which credentials you send. This is what the tabs below switch between, exactly as on the route above.
  • The persona's own Inbound Authentication method — Interactive or Passthrough — decides how the persona identifies you. Either way an Agent Access Key is issued, and neither changes the configuration below.

Because a persona always identifies you by an Agent Access Key, the entry's third mode — Passthrough (No Agent Access Key) — has no tab here. It applies to the LLM Registry entry route only.

claude mcp add --transport http <persona-name> "https://<gateway-host>/p/<persona-id>" \
  --header 'X-Agent-Key: <your-agent-access-key>'

export ANTHROPIC_BASE_URL="https://<gateway-host>/p/<persona-id>/llm/<registry-entry-id>"
export ANTHROPIC_API_KEY="<your-agent-access-key>"
export ANTHROPIC_MODEL="<model-id>"

The same Agent Access Key appears twice on purpose: once as the MCP header for the tools socket, once in ANTHROPIC_API_KEY for the model route.

Restart Claude Code afterwards, then run claude mcp list to confirm the persona's tools are registered.

Registering the tools socket another way​

claude mcp add is the quickest route, but two alternatives wire the same endpoint:

npx @cequenceai/mcp-cli@latest claudecode \
  --url "https://<gateway-host>/p/<persona-id>" \
  --name "<persona-name>" \
  --header 'X-Agent-Key: <your-agent-access-key>'

Or commit a config file and launch against it, which keeps the persona out of your global Claude Code config:

.mcp-strict.json
{
  "mcpServers": {
    "<persona-name>": {
      "type": "http",
      "url": "https://<gateway-host>/p/<persona-id>",
      "headers": { "X-Agent-Key": "<your-agent-access-key>" }
    }
  }
}
claude --mcp-config .mcp-strict.json --strict-mcp-config

The headers block and the --header flag are always needed on this route: an Agent Access Key is required whatever the entry's credential mode.

Using a Claude Pro/Max plan​

If you sign in to Claude Code with a Claude Pro or Max plan rather than an API key, the plan's own token is the provider credential, and passthrough forwards it untouched so usage bills against your plan.

This applies to either passthrough mode, on either route. The change is the line you leave out:

export ANTHROPIC_BASE_URL="https://<gateway-host>/llm/<url-prefix>"
export ANTHROPIC_CUSTOM_HEADERS="X-Agent-Key: <your-agent-access-key>"
export ANTHROPIC_MODEL="<model-id>"

ANTHROPIC_API_KEY is deliberately absent. Claude Code sends the token from your plan sign-in. Setting ANTHROPIC_API_KEY would override that token and silently switch you to API billing.

caution

If ANTHROPIC_API_KEY is already exported in your shell profile from an earlier setup, run unset ANTHROPIC_API_KEY before starting Claude Code. A leftover value takes precedence over your plan token, and the switch to API billing is silent.

This mode has no equivalent on an API Key entry, where the gateway holds the credential and no plan token is in play. It has none on a Bedrock entry either: Claude Code's Bedrock mode doesn't use a plan sign-in.

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
<persona-name>Any short name you want Claude Code to use for this MCP server locally
<registry-entry-id>The LLM Registry entry's ID in the entry's URL
<model-id>A model identifier from the entry's Allowed Models list, for example claude-opus-4-8
<inference-profile-id>On a Bedrock entry, the cross-region inference profile from Allowed Models, for example global.anthropic.claude-sonnet-5
<your-agent-access-key>Generate from the entry's Agent Access Keys step, or the persona's Connect flow. Plaintext is shown once.
<your-anthropic-api-key>Your own Anthropic API key, needed only in the passthrough modes
<your-bedrock-api-key>Your own Amazon Bedrock API key, needed only on a Bedrock entry in passthrough mode

The Connect flow assembles all of this with the real values filled in, ready to copy, on both the LLM Registry entry and the Agent Persona.

Tips​

  • ANTHROPIC_API_KEY must be set, except on a plan. On the API-key modes an empty value sends Claude Code to its own sign-in flow, and it never reaches the gateway, which looks like the gateway ignoring you. On a Claude Pro/Max plan that sign-in is exactly what you want, which is why the variable stays unset there.
  • Claude Code never needs a combined credential. Because it can send ANTHROPIC_CUSTOM_HEADERS, the two credentials stay in separate variables. The <provider-key>::<agent-access-key> form other guides mention is only for clients with a single credential field.
  • Restart after any change. Claude Code reads these variables at startup only, so export them and then start a fresh session.
  • Check the endpoint before the credential. If Claude Code reports a generic authentication error, compare ANTHROPIC_BASE_URL against the URL shown in the Connect flow first. A wrong URL prefix produces the same error message as a bad key.
  • On Bedrock, the two shapes don't mix. ANTHROPIC_BASE_URL and ANTHROPIC_BEDROCK_BASE_URL are read by different modes. A leftover ANTHROPIC_BASE_URL from an earlier Anthropic setup is ignored once CLAUDE_CODE_USE_BEDROCK is on, but it makes the shell confusing to debug — unset it.
  • Unset when finished. If you set these only to try the gateway out, run unset ANTHROPIC_BASE_URL ANTHROPIC_API_KEY ANTHROPIC_CUSTOM_HEADERS ANTHROPIC_MODEL to return Claude Code to its normal behavior, plus unset ANTHROPIC_BEDROCK_BASE_URL CLAUDE_CODE_USE_BEDROCK CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD CLAUDE_CODE_SKIP_BEDROCK_AUTH after a Bedrock setup.
Last updated on