# Claude Code (/docs/integrations/claude-code)

Point Claude Code at the codai root URL, pin every model alias to codai and add the MCP server.

Claude Code needs `ANTHROPIC_BASE_URL=https://ai.codai.ro`, your codai key in `ANTHROPIC_AUTH_TOKEN`, and every model alias pinned to `codai`.

## Before you start [#before-you-start]

- A codai key from [hub.codai.ro](https://hub.codai.ro) → **Keys → Create key** (details in the [quickstart](../gateway/index.mdx)).
- Claude Code installed. No Anthropic account is needed.

## Configure [#configure]

Put the variables in your **user** settings file: `~/.claude/settings.json` (Windows: `%USERPROFILE%\.claude\settings.json`).

```json title="~/.claude/settings.json"
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.codai.ro",
    "ANTHROPIC_AUTH_TOKEN": "codai_xxxxxxxx",
    "ANTHROPIC_MODEL": "codai",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "codai",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "codai",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "codai",
    "CLAUDE_CODE_SUBAGENT_MODEL": "codai"
  }
}
```

- `ANTHROPIC_BASE_URL` is the **root**. Claude Code appends `/v1/messages` itself.
- `ANTHROPIC_AUTH_TOKEN` is sent as `Authorization: Bearer` and needs no approval prompt. `ANTHROPIC_API_KEY` also works (sent as `x-api-key`), but interactive mode asks you to approve it once.
- Pin all four model variables. Otherwise background work and sub-agents ask for built-in `claude-*` ids instead of `codai`.
- Never put the token in a project's `.claude/settings.json` — that file is meant to be committed.
- A value in a settings file beats a shell `export`. Run `/status` to see what Claude Code actually uses.

In the **VS Code extension**, set the same pairs in `claudeCode.environmentVariables` as an array of `{ "name": …, "value": … }`.

## MCP [#mcp]

With a key:

```bash
claude mcp add --transport http codai https://ai.codai.ro/mcp --header "Authorization: Bearer codai_xxxxxxxx"
```

Or in a project `.mcp.json`, reading the key from your environment:

```json title=".mcp.json"
{
  "mcpServers": {
    "codai": {
      "type": "http",
      "url": "https://ai.codai.ro/mcp",
      "headers": { "Authorization": "Bearer ${CODAI_API_KEY}" }
    }
  }
}
```

- `type` is required when `url` is set.
- Do not write `${ANTHROPIC_AUTH_TOKEN}` in the header; it expands to an empty value.

**Without a key (OAuth):** add the server with no header, then run `/mcp` or `claude mcp login codai` and sign in in the browser. codai supports Dynamic Client Registration and PKCE, so nothing else is needed. A server added with a static header that the gateway rejects does not fall back to OAuth — remove the header first.

## What works and what does not [#what-works-and-what-does-not]

| Feature | With codai |
| --- | --- |
| Chat, agent loop, tools, sub-agents | Work, all on `codai` |
| `/v1/messages/count_tokens` | Not served; Claude Code treats it as optional |
| Client `anthropic-beta` headers | Ignored — the gateway sets its own betas |
| `output_config.effort` in the request | Ignored — set effort with `X-Codai-Effort` instead (see [headers](../gateway/headers.mdx)) |

## Troubleshooting [#troubleshooting]

- **`404`** — `ANTHROPIC_BASE_URL` ends in `/v1`. Use the root `https://ai.codai.ro`.
- **Login prompt on first run** — project `env` blocks only load after the first-run wizard. Put the token in user settings or export it in your shell.
- **`Extra inputs are not permitted`** — set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` in the same `env` block.
- **A `claude-*` model shows up in usage** — one of the four model variables is missing.

## Sources [#sources]

Checked 2026-10-02.

- [Claude Code — LLM gateway](https://code.claude.com/docs/en/llm-gateway)
- [Claude Code — environment variables](https://code.claude.com/docs/en/env-vars)
- [Claude Code — settings](https://code.claude.com/docs/en/settings)
- [Claude Code — model configuration](https://code.claude.com/docs/en/model-config)
- [Claude Code — authentication](https://code.claude.com/docs/en/authentication)
- [Claude Code — MCP](https://code.claude.com/docs/en/mcp)