Harness setup

The fastest path is the CLI, which writes the right config for you:

npx @lunaroute/cli setup <harness>

Supported harnesses: pi, claude-code, codex, claude-desktop, opencode, openclaw, hermes, copilot-cli, dsh, zed, and generic (any OpenAI-compatible client).

Per-harness setup pages: Claude Desktop, Claude Code, Codex, Pi, OpenCode, Zed, VS Code. This page covers the manual side — the endpoint, the MCP server, and what each of Claude Code and Codex writes.

Manual setup

For any MCP client that accepts a remote server, add:

{
  "mcpServers": {
    "lunaroute": {
      "url": "https://mcp.lunaroute.com/mcp",
      "headers": { "LUNAROUTE-API-KEY": "lr_..." }
    }
  }
}

Claude Code

Claude Code authenticates with a Bearer token rather than a custom header: lunaroute setup claude-code exports ANTHROPIC_AUTH_TOKEN, and LunaRoute authenticates the lr_ key at the edge. To try it without editing anything, lunaroute run claude-code launches a session on LunaRoute and writes no config (Claude Code setup).

That command wires inference only. The MCP server is a separate step: lunaroute skill install adds it (into ~/.claude.json), or configure it by hand from MCP server. For the desktop app, see Claude Desktop — it is configured through its own third-party inference profile, not through environment variables.

Codex

lunaroute setup codex writes one file — $CODEX_HOME/lunaroute.config.toml (default ~/.codex/lunaroute.config.toml) — holding the named provider and the model, with the key read from the environment (env_key = "LUNAROUTE_API_KEY"). Start it with codex --profile lunaroute; your ~/.codex/config.toml is untouched. For a single session with no file written, lunaroute run codex passes the same provider as -c overrides (Codex setup).

Generic OpenAI-compatible clients

Point the client’s base URL at https://gw.lunaroute.com/v1 and set the API key to your lr_ key. lunaroute setup generic prints the exact environment variables, including an export LUNAROUTE_API_KEY=… line.

Unsupported harnesses

Cursor and Cline can talk to any MCP server, but LunaRoute does not ship a supported setup flow for them — treat their configuration as community/unsupported. Windsurf and Continue are not supported.

If your client can only use a static bearer token for MCP, use Authorization: Bearer lr_….