> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Claude Code

> Set Claude Code's ANTHROPIC_BASE_URL and auth token to send requests through Gateway, and map its model tiers to Gateway models or aliases.

[Claude Code](https://code.claude.com/docs/en/overview) reads its base URL and auth token from environment variables, which you point at Gateway's Anthropic-compatible endpoint. Shared setup: [Building with coding agents](/merge-gateway/coding-agents/overview).

## Configure Claude Code

Set these in the shell where you run `claude`. If you signed in with Anthropic credentials before, run `/logout` and relaunch.

```bash
export MERGE_GATEWAY_API_KEY="mg_..."
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 empty: any value takes precedence over `ANTHROPIC_AUTH_TOKEN` and bypasses Gateway. Confirm both with `/status`, then ask for a small code change.

`ANTHROPIC_DEFAULT_*_MODEL` maps the opus, sonnet, and haiku tiers to Gateway models. Unset, Claude Code sends bare Anthropic IDs such as `claude-sonnet-4-6`, which Gateway also accepts.

## Enable routing

Set a tier to a model alias so its policy picks the model per request:

```bash
export ANTHROPIC_DEFAULT_OPUS_MODEL="@alias/coding-heavy"
export ANTHROPIC_DEFAULT_SONNET_MODEL="@alias/coding-heavy"
```

Keep `ANTHROPIC_DEFAULT_HAIKU_MODEL` pinned: Claude Code sends background tasks to the haiku tier, and a fixed model keeps them cheap and predictable. `default_routing` also works here, using the key's project policy or the organization default.

## Gotchas

* The `/model` picker lists the full Gateway catalog, your organization's aliases, and `default_routing`. Gateway prefixes non-Anthropic IDs with `claude-code/` so the picker keeps them, then strips it. Models with a 1M-token context window carry a `[1m]` suffix.
* The Anthropic endpoint has no `project_id` body field. Scope an organization key with `ANTHROPIC_CUSTOM_HEADERS="X-Project-Id: <project-uuid>"`, or use a project API key.
* Claude Code doesn't read `.env` files. Persist settings per project in the `env` block of `.claude/settings.local.json`, or in your shell profile.
* Each session is one thread in Logs; to change grouping, see [tracing from coding agents](/merge-gateway/observability/tracing#tracing-from-coding-agents)

> **Info**
>
> The [Claude Desktop](/merge-gateway/coding-agents/claude-desktop) app, including its built-in Claude Code surface, ignores these variables

## Next steps

#### [Building with coding agents](/merge-gateway/coding-agents/overview)

Keys, models, aliases, and project scoping

#### [Model aliases](/merge-gateway/routing/model-aliases)

Change a tier's model without new exports