Connect Cursor to a gateway

Cursor reaches an MCP gateway 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.

With an API key

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

{
    "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

For a gateway with OAuth on, the entry carries the client ID that the person managing your identity provider registered for Cursor, and no header:

{
    "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

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 page.

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

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, in the Reason column of the auth-failed event, next to the person's name.

See also

Learn more