> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inceptionlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> Run Claude Code with Mercury 2.5 through a local LiteLLM bridge.

Use `mercury-cc` to launch Claude Code with Mercury 2.5. The launcher runs an isolated local bridge, so your regular `claude` command and Claude Code settings stay unchanged.

<Warning>
  This integration uses [LiteLLM](https://docs.litellm.ai/) as a third-party bridge between Claude Code's Anthropic Messages API and Inception's OpenAI-compatible API. Anthropic does not support routing Claude Code to non-Claude models. Review LiteLLM before using it with sensitive code or credentials.
</Warning>

<Tip>
  Mercury 2.5 supports parallel tool calls, allowing Claude Code to request multiple independent tools in the same turn.
</Tip>

## Prerequisites

* [Claude Code](https://code.claude.com/docs/en/overview)
* macOS or Linux
* Python 3.11 or later
* An [Inception API key](https://platform.inceptionlabs.ai/)

## Setup

<Steps>
  <Step title="Install the local bridge">
    Set `PYTHON_BIN` to a Python 3.11+ executable, then install the tested LiteLLM version in an isolated environment:

    ```bash theme={null}
    PYTHON_BIN=python3
    "$PYTHON_BIN" --version

    mkdir -p "$HOME/.mercury-cc" "$HOME/.local/bin"
    chmod 700 "$HOME/.mercury-cc"
    "$PYTHON_BIN" -m venv "$HOME/.mercury-cc/.venv"
    "$HOME/.mercury-cc/.venv/bin/pip" install 'litellm[proxy]==1.99.0'
    ```
  </Step>

  <Step title="Store your Inception API key">
    Enter your API key when prompted. The key stays in a user-only file and is only loaded by the local bridge.

    ```bash theme={null}
    bash -c 'read -rsp "Inception API key: " key; printf "\n"; printf "%s" "$key" > "$HOME/.mercury-cc/api-key"'
    chmod 600 "$HOME/.mercury-cc/api-key"
    ```
  </Step>

  <Step title="Create the mercury-cc launcher">
    Create `~/.mercury-cc/mercury-cc`:

    ```bash theme={null}
    #!/usr/bin/env bash
    set -euo pipefail

    mercury_home="$HOME/.mercury-cc"
    key_file="${mercury_home}/api-key"
    pid_file="${mercury_home}/proxy.pid"
    port="${MERCURY_CC_PORT:-4000}"
    proxy_url="http://127.0.0.1:${port}"

    proxy_ready() {
      curl -fsS "${proxy_url}/v1/models" 2>/dev/null \
        | grep -q 'inception/mercury-2.5'
    }

    if [[ "${1:-}" == "--stop" ]]; then
      if [[ ! -f "$pid_file" ]]; then
        echo "Mercury bridge is not running."
        exit 0
      fi

      read -r pid < "$pid_file"
      if kill -0 "$pid" 2>/dev/null; then
        kill "$pid" 2>/dev/null || true
        echo "Mercury bridge stopped."
      else
        echo "Mercury bridge is already stopped."
      fi
      rm -f "$pid_file"
      exit 0
    fi

    if [[ ! -s "$key_file" ]]; then
      echo "Inception API key not found at ${key_file}" >&2
      exit 1
    fi

    if ! proxy_ready; then
      INCEPTION_API_KEY="$(<"$key_file")" \
        nohup "${mercury_home}/.venv/bin/litellm" \
          --model inception/mercury-2.5 \
          --alias mercury \
          --drop_params \
          --host 127.0.0.1 \
          --port "$port" \
          >"${mercury_home}/proxy.log" 2>&1 &
      echo "$!" > "$pid_file"

      for _ in {1..60}; do
        proxy_ready && break
        sleep 0.25
      done
    fi

    if ! proxy_ready; then
      echo "Mercury bridge failed to start. See ${mercury_home}/proxy.log" >&2
      exit 1
    fi

    export ANTHROPIC_BASE_URL="$proxy_url"
    export ANTHROPIC_AUTH_TOKEN="mercury-local"
    unset ANTHROPIC_API_KEY

    export ANTHROPIC_MODEL="mercury"
    export ANTHROPIC_DEFAULT_HAIKU_MODEL="mercury"
    export ANTHROPIC_DEFAULT_SONNET_MODEL="mercury"
    export ANTHROPIC_DEFAULT_OPUS_MODEL="mercury"
    export CLAUDE_CODE_SUBAGENT_MODEL="mercury"
    export CLAUDE_CODE_MAX_CONTEXT_TOKENS=260000

    exec claude "$@"
    ```

    Make it executable and link it into `~/.local/bin`:

    ```bash theme={null}
    chmod 700 "$HOME/.mercury-cc/mercury-cc"
    ln -sf "$HOME/.mercury-cc/mercury-cc" "$HOME/.local/bin/mercury-cc"
    ```

    <Note>
      If `~/.local/bin` is not already on your `PATH`, link the launcher into another user-writable directory that is. This setup does not modify your shell configuration.
    </Note>
  </Step>

  <Step title="Launch Claude Code with Mercury">
    Start an interactive session:

    ```bash theme={null}
    mercury-cc
    ```

    Run `/status` inside Claude Code to confirm that the API base URL is `http://127.0.0.1:4000` and the model is `mercury`.
  </Step>
</Steps>

## Verify the integration

Run an end-to-end prompt:

```bash theme={null}
mercury-cc -p "Reply with exactly: Mercury 2.5 is connected."
```

You can also call the bridge's Anthropic-compatible endpoint directly:

```bash theme={null}
curl http://127.0.0.1:4000/v1/messages \
  -H 'Authorization: Bearer mercury-local' \
  -H 'Anthropic-Version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "mercury",
    "max_tokens": 2048,
    "messages": [{"role": "user", "content": "Say hello from Mercury 2.5."}]
  }'
```

<Note>
  This request uses `max_tokens` because it targets the Anthropic Messages interface exposed by the local bridge. Direct requests to Inception's Chat Completions API use `max_completion_tokens`.
</Note>

## Stop the bridge

```bash theme={null}
mercury-cc --stop
```

<Accordion title="Troubleshooting">
  * **Bridge startup fails:** Run `tail -n 50 ~/.mercury-cc/proxy.log` and confirm that Python is version 3.11 or later.
  * **`mercury-cc` is not found:** Run `~/.mercury-cc/mercury-cc` directly or link it into a directory already on your `PATH`.
  * **Claude Code logs `unrecognized_model`:** Claude Code may show this warning for the custom `mercury` alias. Requests still route to Mercury 2.5.
  * **Regular Claude Code behavior:** Launching `claude` directly continues to use your existing Claude Code configuration.
</Accordion>

[Claude Code gateway documentation](https://code.claude.com/docs/en/llm-gateway) · [LiteLLM Inception provider](https://docs.litellm.ai/docs/providers/inception)