Coding agents and IDEs

Claude Code

Route Claude Code through Merge Gateway by overriding the Anthropic base URL

Claude Code is Anthropic’s terminal coding agent. Override its base URL and auth token to send every request through Merge Gateway, with routing policies, cost governance, and full request observability in the Gateway dashboard.

Before you start

  • Install Claude Code: curl -fsSL https://claude.ai/install.sh | bash or npm install -g @anthropic-ai/claude-code
  • Grab an API key. An organization key from gateway.merge.dev/api-keys works everywhere; a project API key, created from a project’s API keys tab, additionally scopes every request to that project so its routing policy and budget apply automatically. See Projects.
  • Pick the Claude models you want available. Gateway model names take the form provider/model, for example anthropic/claude-opus-5 and anthropic/claude-sonnet-5. Browse the full catalog with GET /v1/models or in the dashboard.

Configure Claude Code

1

Export environment variables in your project shell

In a terminal scoped to your project, set:

$export MERGE_GATEWAY_API_KEY="mg_your_key"
$export ANTHROPIC_BASE_URL="https://api-gateway.merge.dev/v1/anthropic"
$export ANTHROPIC_AUTH_TOKEN="$MERGE_GATEWAY_API_KEY"
$export ANTHROPIC_API_KEY=""
$export ANTHROPIC_DEFAULT_OPUS_MODEL="anthropic/claude-opus-5"
$export ANTHROPIC_DEFAULT_SONNET_MODEL="anthropic/claude-sonnet-5"
$export ANTHROPIC_DEFAULT_HAIKU_MODEL="anthropic/claude-haiku-4-5-20251001"

ANTHROPIC_API_KEY must be explicitly empty, or Claude Code prefers it over ANTHROPIC_AUTH_TOKEN and bypasses Gateway. The ANTHROPIC_DEFAULT_*_MODEL variables map Claude Code’s opus, sonnet, and haiku tiers to the Gateway provider/model slugs you want to use. To let a routing policy pick the model instead of pinning slugs, see Enable routing below.

If you previously signed in to Claude Code with Anthropic credentials, run /logout and relaunch so the env vars take effect.

2

Launch Claude Code

Run claude in your project. The new session uses Gateway via the env vars you exported above.

3

Verify with /status

Run /status. Confirm the output shows:

  • Auth token: ANTHROPIC_AUTH_TOKEN
  • Anthropic base URL: https://api-gateway.merge.dev/v1/anthropic

Then send a quick prompt to confirm streaming works, and ask Claude Code to make a small code change to verify tool calls and file edits flow through Gateway. The request appears in your Gateway dashboard within a few seconds.

Enable routing

Pinned model slugs mean Claude Code always uses the exact model you set. To let a routing policy pick the vendor and model per request, set the tier variables to the sentinel value default_routing instead of a model slug:

$export ANTHROPIC_DEFAULT_OPUS_MODEL="default_routing"
$export ANTHROPIC_DEFAULT_SONNET_MODEL="default_routing"
$export ANTHROPIC_DEFAULT_HAIKU_MODEL="default_routing"

Gateway resolves the policy from your API key: a project API key uses that project’s policy, an organization key falls back to the org default. If neither exists, requests fail with a model_required error, so create a policy first.

Setting all three tiers routes everything through the policy, including Claude Code’s background haiku-tier tasks. To keep background tasks cheap and predictable, leave ANTHROPIC_DEFAULT_HAIKU_MODEL pinned to a fixed model and set only the opus and sonnet tiers to default_routing.

Scope requests to a project

Gateway’s Anthropic-compatible endpoint has no project_id request field, so scope Claude Code to a project in one of two ways:

  • Project API key (recommended). Create the key from the project’s API keys tab in the dashboard. Every request made with it attributes to the project automatically, and the project’s routing policy and budget apply. Nothing extra to configure in Claude Code.

  • X-Project-Id header. Keep an organization key and send the project’s ID (shown on the project’s page) with each request:

    $export ANTHROPIC_CUSTOM_HEADERS="X-Project-Id: 4f8b2c6e-9d1a-4e7a-b3f5-2c8d0a6e1b47"

Claude Desktop app

Anthropic’s Claude Desktop app (including its Chat, Cowork, and built-in Claude Code surfaces) can also route through Gateway. Unlike the CLI, it isn’t configured with ANTHROPIC_BASE_URL; it has its own third-party inference settings, model discovery, and MDM story. See the dedicated Claude Desktop guide for the full setup.

Caveats

Claude Code reads both ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN. If ANTHROPIC_API_KEY is set to anything non-empty, it wins and Claude Code bypasses your Gateway base URL. The explicit export ANTHROPIC_API_KEY="" in the recipe above clears any inherited value for the session.

The ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL env vars override the model identifier Claude Code sends in each request. Set them to Gateway provider/model slugs (anthropic/claude-opus-5, anthropic/claude-sonnet-5, anthropic/claude-haiku-4-5-20251001), or to default_routing to hand the choice to a routing policy (see Enable routing). Without these overrides Claude Code sends the bare Anthropic alias (for example claude-sonnet-4-6), which Gateway accepts but does not let you steer per request.

The recipe above lives in your shell, so it applies only to that terminal. To persist it, add the same export lines to your shell profile (~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish), or use a project-scoped .claude/settings.local.json with an env block (Claude Code does not read .env files).

Claude Code relies on tool calls to read and edit files. Tool calling works through Gateway for any model whose capabilities.supports_tool_calling is true on the chosen vendor route. See Tool calling.

Next steps

Routing policies

Let Gateway pick the best vendor for each Claude Code request

Projects

Use a project API key so Claude Code usage is tracked separately

Cost governance

Cap spend and restrict which models Claude Code can hit