Cursor

Manage your account with MCP

To inspect usage or manage ZRouter routers, keys, and enabled limits from your assistant, connect the account MCP server. This manages your ZRouter account without changing the assistant's model provider. The instructions below cover routing model requests instead.

Compatibility first

Prepaid accounts: plain text chat only, when the client sends no tools. Cursor Agent workflows require a standalone deployment because prepaid accounts reject tool definitions and results. A chat mode can still fail if Cursor includes tools or unsupported content automatically.

Cursor's custom API keys apply to supported chat models. Tab completion uses Cursor's built-in models. Cursor's own plan and usage rules also apply. See Cursor API key documentation.

Connection requirements

Use a public HTTPS gateway endpoint reachable from Cursor's servers. localhost, a LAN address, or a private development server is not sufficient for Cursor's hosted request path. See the Cursor support team's explanation.

For prepaid text chat, create an account key and fund the balance. For an agent-capable standalone gateway, ask the operator for a dedicated managed key. Use an exact model ID returned by /v1/models; do not assume an example model is enabled.

Configure Cursor

1. Open Cursor Settings → Models.
2. Enter the ZRouter key in the OpenAI API key field.
3. Enable Override OpenAI Base URL and set https://zrouter.si/v1, for hosted text chat. For Agent workflows, use the URL of your separate standalone gateway, including its deployment path prefix.
4. Save the configuration. Add or select the gateway model ID in the model list if your installed version permits custom models.
5. Start a new text chat with that model. Inspect ZRouter usage and available request logs after a completed request.

The API key is sent through Cursor's backend to the configured gateway. Avoid putting a provider BYOK secret in this field: it needs the ZRouter gateway credential.

BYOK and feature boundaries

Customer BYOK requires X-ZRouter-BYOK: true and a saved key for the selected provider-qualified model. The basic Cursor override does not provide a documented arbitrary-header setting, so these instructions use gateway-funded credits. Merely saving a BYOK key in ZRouter does not make Cursor requests use it.

Tab, cloud features, and other Cursor services are not redirected simply by changing this base URL. Do not assume every model or Cursor feature can use a custom gateway.

Troubleshooting

• For 401, check the override is still enabled and the key belongs to ZRouter, not OpenAI.
• For connection failure, confirm public HTTPS reachability from outside your machine.
• For model validation errors, check the exact identifier and your version's custom-model support. Do not rename a model to claim capabilities it lacks.
• For prepaid tools is not supported, use a text-only client or a separate standalone gateway for agent work.

See shared troubleshooting. Local ZRouter development is better checked with curl or an SDK until a public HTTPS endpoint is available.