2026 OmniRoute Cursor Setup: One Gateway, Two Clients

Symptom: You paste the same http://localhost:20128/v1 URL into Cursor and Claude Code, then one client fails or ignores the gateway.

Fastest fix: Run one OmniRoute instance, but configure Claude Code with the gateway root URL without /v1; configure Cursor separately according to its desktop or CLI path. Then test routing and fallback independently.

This guide is for developers using Cursor and Claude Code together, engineers keeping an AI Gateway online on a remote Mac, and teams that need one set of provider credentials with controlled failover.

Last updated August 12, 2026. Commands and endpoint behavior were checked against the OmniRoute repository and CLI integration documentation, Cursor documentation, and Anthropic’s gateway documentation.

One OmniRoute instance, two endpoint rules

The common mistake is confusing a shared gateway with identical client configuration.

The request path should look like this:

Cursor desktop or Cursor CLI
        |
        | client-specific endpoint format
        v
OmniRoute
http://127.0.0.1:20128
        |
        | routing, authentication, retry, fallback
        +--> Provider A
        +--> Provider B
        +--> Provider C

OmniRoute exposes an OpenAI-compatible path for clients that expect one. Claude Code uses the Anthropic Messages API path. Its gateway variable must point to the root, because Claude Code appends /v1/messages itself. The OmniRoute Claude Code guide explicitly states that ANTHROPIC_BASE_URL should not include a /v1 suffix. (Claude Code configuration guide)

That creates two different values:

Cursor desktop, Cursor CLI, and MCP are not interchangeable. Cursor’s own documentation says custom API keys apply to standard chat models, while specialized features such as Tab Completion can continue using built-in models. (Cursor API key documentation)

Decision rule: If you need predictable endpoint control, test Cursor CLI first. If you need the full Cursor desktop experience, treat OmniRoute as a partial provider path until each required feature passes verification.

Installation and the minimum healthy gateway

Do not begin by changing client settings. First prove that OmniRoute itself is running and serving a model catalog.

Use the project’s documented installation path for your machine, then complete this minimum loop:

1. Install or update OmniRoute.
2. Start the service on the configured port.
3. Open the local dashboard only to confirm that the process is alive.
4. Create an inference API key.
5. Run a health check.
6. Read the model catalog.
7. Send one minimal chat request.

A typical local address is:

http://127.0.0.1:20128

The port and local-versus-remote behavior are documented in OmniRoute’s CLI integration material. With no remote flags, the CLI targets the local server; with a remote context or explicit remote address, it fetches the catalog from that server. (OmniRoute CLI integration matrix)

Use placeholders for secrets:

export OMNIROUTE_URL="http://127.0.0.1:20128"
export OMNIROUTE_API_KEY="oma_live_REPLACE_ME"

curl -fsS "$OMNIROUTE_URL/health"

curl -fsS \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  "$OMNIROUTE_URL/v1/models"

The exact health route can vary with the active build. If /health returns 404, inspect the project’s current setup guide or CLI diagnostics rather than assuming that the server is down. The important evidence is not the dashboard page. You need a successful health response, a non-empty model response, and one real inference request.

For a minimal OpenAI-compatible probe, adapt the model ID returned by /v1/models:

curl -fsS "$OMNIROUTE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "REPLACE_WITH_MODEL_ID",
    "messages": [
      {"role": "user", "content": "Reply with the word gateway."}
    ],
    "max_tokens": 16
  }'

The three checks catch different failures:

• Health fails: the process, port, firewall, or bind address is wrong.
• Health works but models are empty: credentials, provider setup, or catalog discovery is incomplete.
• Models work but chat fails: the selected model, wire format, key scope, or provider route is wrong.

You can use the MacHTML console as an operational reference point for remote machine access, but do not treat a visible console as proof that every client can reach the gateway.

Remote warning: 127.0.0.1 means “this machine.” It is correct only when OmniRoute and the client run on the same Mac. For a remote Mac, use a reachable private address or hostname and restrict the port to the required network path.

Claude Code root URL and authentication

Claude Code is usually the easier half of this dual-client setup because its gateway variables are explicit.

The main path is:

export ANTHROPIC_BASE_URL="http://127.0.0.1:20128"
export ANTHROPIC_AUTH_TOKEN="oma_live_REPLACE_ME"
export ANTHROPIC_MODEL="REPLACE_WITH_MODEL_ID"

claude

Do not append /v1 to ANTHROPIC_BASE_URL. Claude Code sends Anthropic Messages API traffic and constructs the request path below the configured root. Anthropic’s gateway documentation also describes a unified endpoint pattern without a /v1 suffix for gateway integrations. (Anthropic LLM gateway documentation)

OmniRoute’s documented launcher can reduce manual mistakes:

omniroute launch

For a remote service:

omniroute launch \
  --remote "http://REMOTE_MAC_ADDRESS:20128" \
  --api-key "oma_live_REPLACE_ME"

The launcher resolves the active context, checks the server, injects the environment, and starts Claude Code according to the OmniRoute configuration guide.

Keep the manual environment setup as your fallback path. It is easier to inspect when a shell, service manager, or remote session behaves unexpectedly.

After changing any variable, fully quit and restart Claude Code. The environment is read at startup. A running process will not reliably adopt a new base URL from your shell.

Model discovery has another boundary. The native model picker may show only model IDs matching Claude- or Anthropic-style naming when gateway discovery is enabled. A non-Claude model can still require an explicit ANTHROPIC_MODEL value. Do not infer that an empty picker means the gateway has no models.

For a controlled check:

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
export ANTHROPIC_MODEL="provider/model-id"
claude

If you use per-model profiles, OmniRoute’s setup-claude command can generate separate Claude Code configuration directories from the live model catalog. The token is injected at launch rather than written into each profile.

Advantages:

• Less hand-editing.
• Separate model profiles.
• Easier remote and local switching.
• Lower risk of committing a token into a settings file.

Limitations:

• Generated profiles depend on the live catalog.
• A renamed provider model can make a profile stale.
• The picker may not expose every non-Anthropic model.
• You still need to restart the client after changing environment values.

Cursor desktop, Cursor CLI, and MCP paths

Cursor needs a more careful decision because “Cursor support” can mean three different things.

Cursor desktop lets you add provider API keys through its model settings. Its official documentation limits custom API keys to standard chat models. Specialized features can continue to use Cursor’s own models, even after the custom key passes verification. (Cursor API key documentation)

Cursor CLI exposes a separate endpoint control:

export CURSOR_API_KEY="REPLACE_ME"

cursor-agent status

cursor-agent \
  --endpoint "http://127.0.0.1:20128/v1" \
  --model "REPLACE_WITH_MODEL_ID" \
  "Reply with the word gateway."

The exact flag syntax should be checked with the installed binary:

cursor-agent --help

Cursor’s CLI authentication documentation lists --endpoint for custom endpoint issues and CURSOR_API_KEY for API-key authentication. (Cursor CLI authentication documentation)

MCP is different again. An MCP connection can provide tools, files, or context to an agent. It does not automatically replace the model provider endpoint used by Cursor desktop or Claude Code. If your goal is unified model routing, configure the model path first. Add MCP only after the client can complete a normal request.

When Cursor verification fails, use this order:

1. Identify whether you are testing desktop, CLI, or MCP.
2. Confirm the client’s expected API format.
3. Check whether the model is a supported standard chat model.
4. Test the same model with curl.
5. Read the OmniRoute request log.
6. Only then change keys or provider settings.

This avoids a common false diagnosis. A successful desktop verification does not prove that Tab Completion, agent tools, and every built-in feature passed through OmniRoute.

Fallback chains and quota failures

A direct model connection, automatic routing, and a custom fallback chain are different configurations.

A direct connection sends every request to one target. Automatic routing chooses a target based on the gateway’s rules. A custom fallback chain defines what should happen when the first target fails.

The chain is not testable if you have only one working provider. The project may advertise a large provider catalog and quota-aware routing, but provider counts, free allowances, compression gains, and comparative claims are project-reported or third-party observations, not independent measurements. Treat them as planning inputs, not guarantees. (OmniRoute feature documentation)

Use at least two reachable providers and make the order visible:

Primary: provider-a/strong-model
Fallback: provider-b/standard-model

Then run a repeatable drill:

1. Fix the primary model explicitly.
2. Send a request and record the returned model identifier.
3. Temporarily disable the primary provider, revoke its test key, or apply a controlled failure condition.
4. Send the same request again.
5. Confirm that OmniRoute selected the fallback target.
6. Inspect the route decision and error log.
7. Restore the primary provider.
8. Repeat once after a gateway restart.

Do not simulate failure by unplugging the entire network. That tests connectivity, not quota fallback. A useful drill produces a provider-level error while leaving the gateway reachable.

No fallback usually means one of these conditions:

• The second provider is not configured.
• The fallback target uses an invalid model ID.
• The first provider returns a successful but limited response.
• The error is not classified as retryable.
• The client retries locally instead of letting OmniRoute route.
• The request format is accepted by one provider but rejected by the next.
• The route is configured for a different API family.

Record the final model identifier, response status, gateway log entry, and route decision. A different answer alone is not proof of a successful switch.

Remote Mac deployment and access control

A remote Mac becomes useful when OmniRoute and the coding clients must remain available while your laptop sleeps, changes networks, or moves between locations.

The safe topology is:

Developer device
      |
Private network, tunnel, or restricted access layer
      |
Remote Mac
      |
OmniRoute on controlled bind address
      |
Model providers

Avoid exposing the gateway directly to the public internet unless you have a deliberate access-control design. Use scoped keys where available. Separate personal testing keys from team keys. Do not place provider secrets in a shared shell history, repository, or generated profile.

For a remote client, replace the local base address:

export ANTHROPIC_BASE_URL="http://REMOTE_MAC_ADDRESS:20128"
export ANTHROPIC_AUTH_TOKEN="oma_live_REPLACE_ME"

For Cursor CLI, use the remote OpenAI-compatible path required by that client:

cursor-agent \
  --endpoint "http://REMOTE_MAC_ADDRESS:20128/v1" \
  --api-key "REPLACE_ME" \
  "Run the gateway smoke test."

Remote access adds three failure classes that do not exist in a same-machine setup:

• Network reachability: the client cannot resolve or reach the remote address.
• Permission scope: the key can reach the server but not the intended endpoint.
• Recovery behavior: the gateway works until a restart, sleep event, or process crash.

Use this delivery checklist:

For a short personal test, keep OmniRoute local. This reduces network and permission variables. For continuous access, cross-device use, or a small team, move the gateway to a controlled remote Mac only after the local dual-client test passes.

If you are preparing a managed remote environment, review the MacHTML help resources before deciding how clients, credentials, and machine access should be handed to other users.

FAQ: endpoint and fallback decisions

Can one OmniRoute server handle both tools?

Yes, but the client settings remain separate. Use one server process and one provider policy, then give Claude Code the root URL and test Cursor through its supported desktop or CLI path. Sharing the gateway instance reduces duplicated routing configuration. Copying the same URL string into both clients is the part that causes failures.

Does Claude Code need /v1 in the base URL?

No. Use the OmniRoute root address. Claude Code adds the Anthropic request path. A /v1 suffix belongs to clients that expect an OpenAI-compatible base path, not automatically to every client connected to the same gateway. Restart the process after changing ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, or ANTHROPIC_MODEL.

Should you use Cursor desktop or Cursor CLI?

Choose Cursor CLI when endpoint control and repeatable shell tests are the priority. Choose Cursor desktop when editor workflow matters more, but verify each required feature because custom API keys are documented for standard chat models only. Use MCP separately for tools and context. It is not a substitute for validating the model request path.

Why does fallback look inactive after a quota event?

First prove that the gateway can reach two providers. Then create a controlled primary failure and inspect the route decision. Some quota conditions look like successful responses, so they may not trigger the same fallback path as an authentication error or timeout. Always compare the gateway log with the final model identifier.

What changes when OmniRoute runs on a remote Mac?

localhost stops being valid for clients running elsewhere. Use a reachable private address, limit access to the required network, and test recovery after restarting the gateway. A remote setup should pass health, model discovery, real inference, fallback, key isolation, and restart checks before other developers rely on it.

The final choice: local test or remote Mac

Your current local setup is cheaper to validate, but it has real weaknesses: the Mac can sleep, the address is tied to one machine, and provider keys may become scattered across separate client settings. A laptop-based gateway also becomes difficult to share when several developers need the same routing policy or when a long-running agent must survive a network change.

A MacHTML remote Mac is the stronger fit when you need continuous availability, cross-device access, or a controlled shared environment. Keep the gateway private, use scoped credentials, and treat the acceptance table above as the handoff requirement rather than relying on a dashboard screenshot.

For a short experiment, stay local. When the gateway must remain online while you disconnect, switch networks, or hand access to a team, move the verified OmniRoute setup to a managed remote Mac environment and validate recovery before expanding usage.

FAQ