Using Polaris from Claude Code

There are two ways to bring the Polaris Advisor into Claude Code:

1. As a tool — the Advisor MCP endpoint. Claude Code keeps using its normal Claude model and calls the Advisor for grounded, cited answers. This is the recommended integration — it's what MCP is for, and it doesn't degrade Claude Code's coding ability.
2. As the model backend — via the completions endpoint (this page). Every Claude Code turn is answered by the Advisor. This is what the rest of this guide covers.

The Advisor is a knowledge provider, not a coding model

The completions endpoint serves the Advisor: grounded, cite-then-verified answers from a published brain. It has no tool-use/function-calling and only answers from the brain's corpus. Pointing Claude Code's model at it means Claude Code loses its coding/agentic abilities — useful for a Q&A harness over your brain, not for writing code. For most workflows, prefer the MCP endpoint.

Why a gateway is required

Claude Code speaks only the Anthropic Messages API (/v1/messages) to whatever ANTHROPIC_BASE_URL points at — it does not call OpenAI-style /v1/chat/completions (Gateway protocol reference). Polaris speaks OpenAI Chat Completions. So you run a small translation gateway in the middle:

Claude Code ──(Anthropic /v1/messages)──▶ LiteLLM ──(OpenAI /chat/completions)──▶ Polaris Advisor
                                              │                                      (sk-polaris-… key)
                                              └── translates Messages ⇄ Completions, streams SSE

LiteLLM is the common choice; any Anthropic→OpenAI proxy works.

1. Mint an Advisor API key

From the SPA (Settings → API keys) or the CLI — see Managing keys:

APP_CONFIG=$(pwd)/env/local/app.env uv run python -m app.cli apikey mint \
  --brain-id calliope --label claude-code            # → sk-polaris-xxxx (shown once)

2. Configure the LiteLLM gateway

litellm.config.yaml — map a model name to the brain-scoped Polaris completions URL, with the key:

model_list:
  - model_name: polaris-advisor
    litellm_params:
      model: openai/polaris-advisor                       # openai/ = OpenAI-compatible provider
      api_base: http://localhost:8088/v1/brains/calliope  # brain-scoped Polaris base_url
                                                          # deployed: https://<host>/v1/brains/<id>
                                                          #   (see docs EDGE.md)
      api_key: os.environ/POLARIS_API_KEY                 # your sk-polaris-… key

export POLARIS_API_KEY=sk-polaris-xxxx
litellm --config litellm.config.yaml --port 4000          # exposes an Anthropic /v1/messages surface

3. Point Claude Code at the gateway

Set these in your shell or in ~/.claude/settings.json (global) / .claude/settings.local.json (per-project, gitignored). See the LLM gateway connection docs and environment variables.

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4000",
    "ANTHROPIC_AUTH_TOKEN": "<litellm-virtual-or-master-key>",
    "ANTHROPIC_MODEL": "polaris-advisor",
    "CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING": "1"
  }
}

• ANTHROPIC_AUTH_TOKEN → sent as Authorization: Bearer … to LiteLLM (its virtual/master key — not your sk-polaris-…, which lives inside the gateway config). Use ANTHROPIC_API_KEY instead if your gateway expects an x-api-key header.
• ANTHROPIC_MODEL selects the model_name you defined in LiteLLM.

Verify the gateway before relying on it:

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" -H "content-type: application/json" \
  -d '{"model":"polaris-advisor","max_tokens":256,"messages":[{"role":"user","content":"Do I need a CA lender license?"}]}'

A JSON reply starting with {"id":"msg_… means Claude Code can reach the Advisor.

Caveats

Requirement	Why	Fix
Streaming (SSE)	Claude Code hangs without it.	Polaris streams; LiteLLM forwards it. ✓
Tool use / function-calling	Claude Code's /tools, file edits, etc. rely on it.	Unsupported by the Advisor — a model-backend setup is Q&A only. Use MCP to keep tools.
Extended / "adaptive" thinking	Newer Claude Code sends a thinking field the Advisor rejects (400).	CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1.
Unrecognized beta fields	Can 400 on a plain backend.	CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 if you hit Extra inputs are not permitted.

The Advisor's structured citations (the polaris metadata / response_format: json_object) are described in the completions reference; whether they survive to Claude Code depends on how your gateway maps the OpenAI response back to Anthropic Messages.