# Connect Cursor to a gateway

Add an MCP gateway to Cursor with an API key or with a sign-in through your identity provider.

Cursor reaches an [MCP gateway](https://zato.io/docs/ai/mcp/index.html) through an entry in `.cursor/mcp.json` in the project, or in `~/.cursor/mcp.json` for every project, and the gateway's tools then appear in the agent's tool list. The entry has two forms, and which one you write depends on how the gateway is [secured](https://zato.io/docs/ai/mcp/security.html).

## With an API key {#with-an-api-key}

For a gateway secured with an API key or a static bearer token, the entry carries the header:

```json
{
    "mcpServers": {
        "billing": {
            "url": "https://api.example.com/mcp/billing",
            "headers": {"X-API-Key": "the-actual-key"}
        }
    }
}
```

To keep the key out of the file, write `${env:BILLING_KEY}` in place of the value and set the variable in the environment Cursor starts from.

## With OAuth {#with-oauth}

For a gateway with [OAuth](https://zato.io/docs/ai/mcp/oauth.html) on, the entry carries the client ID that the person managing your identity provider registered for Cursor, and no header:

```json
{
    "mcpServers": {
        "billing": {
            "url": "https://api.example.com/mcp/billing",
            "auth": {
                "CLIENT_ID": "<client-id>"
            }
        }
    }
}
```

Without the `auth` block, Cursor tries to register itself with the provider, which works with Keycloak when dynamic registration is on and never with Entra ID.

## What the identity provider needs {#what-the-identity-provider-needs}

The registration for Cursor is a public client with these redirect URIs:

- `http://localhost:8787/callback` - the local address Cursor listens on during the sign-in
- `https://www.cursor.com/agents/mcp/oauth/callback` - the hosted address its cloud agents use

Cursor asks for a token without naming the gateway, so the audience of the token is whatever the provider issues for the client and the scopes - with Entra ID, that means the API's scope has to be among the registration's permissions and in the gateway's Scopes field, as described on the [OAuth](https://zato.io/docs/ai/mcp/oauth.html#microsoft-entra-id) page.

## The sign-in {#the-sign-in}

1. After the entry is saved, the server appears under **Cursor Settings** > **Tools and MCP** with a **Needs login** state.
2. Clicking it opens the browser at your identity provider's sign-in page.
3. After the sign-in, the browser returns to Cursor, the state turns green and the gateway's tools are listed under the server.

Cursor keeps the token and refreshes it on its own until the provider's session ends. Removing the server from the settings drops it.

## When access is refused {#when-access-is-refused}

A person whose token the gateway does not accept - outside the group the gateway's bearer definition lists, or signed in to the wrong tenant - sees the server stay red under **Tools and MCP**, with a 401 in its log, and the **Needs login** state returns. The reason is in the gateway's [audit log](https://zato.io/docs/ai/mcp/audit-log.html), in the **Reason** column of the `auth-failed` event, next to the person's name.

## See also {#see-also}

- [OAuth](https://zato.io/docs/ai/mcp/oauth.html) - How the sign-in works and how to set up Entra ID or Keycloak
- [Sharing with clients](https://zato.io/docs/ai/mcp/sharing-with-clients.html) - The export with the gateway's address and the other clients' snippets
- [MCP gateways](https://zato.io/docs/ai/mcp/index.html) - Configuration and the governance controls

## Learn more {#learn-more}

- [MCP tutorial](https://zato.io/tutorials/mcp/01.html) - Expose Python services as AI tools and connect Claude Code in minutes
- [AI Integrations overview](https://zato.io/docs/ai/) - Both directions of AI traffic in one platform, and where to start
- [MCP gateway reference](https://zato.io/docs/ai/mcp/) - Configuration, endpoint behavior and the governance controls
- [Tool schemas](https://zato.io/docs/ai/mcp/tool-schemas.html) - How a service's docstring and declared I/O become its tool definition
- [MCP gateway security](https://zato.io/docs/ai/mcp/security.html) - API keys, Basic Auth and bearer tokens for AI agents
- [MCP response controls](https://zato.io/docs/ai/mcp/response-controls.html) - PII removal, prompt-injection safeguards and token-denominated size caps
- [MCP audit log](https://zato.io/docs/ai/mcp/audit-log.html) - What each agent did, when and with what outcome - payloads never recorded
- [MCP alerts](https://zato.io/docs/ai/mcp/alerts.html) - Failing backends, agents stuck in a loop and gateways with too many tools
- [Cost and limits](https://zato.io/docs/ai/cost-and-limits.html) - Every knob that caps AI cost and traffic, with worked examples
- [GitOps for AI integrations](https://zato.io/docs/ai/enmasse.html) - LLM connections and MCP gateways as YAML in version control
- [AI examples](https://zato.io/docs/ai/examples/) - Complete, runnable scenarios - one real-world need per file