Add a Remote MCP Server to Cursor: mcp.json, OAuth and Fixes

A remote MCP server goes into Cursor as one entry in mcp.json, with a url instead of a command:

{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

Put that in ~/.cursor/mcp.json to have the server in every project, or in .cursor/mcp.json inside a project to have it only there [1]. Cursor speaks both Streamable HTTP and the older SSE transport to a URL server [1]. If the server needs you to sign in, Cursor handles OAuth for it [1].

Everything below is checked against Cursor's MCP documentation on 12 October 2026 [1].

TL;DR:

• Global file: ~/.cursor/mcp.json. Project file: .cursor/mcp.json. The url is the MCP endpoint itself, usually ending in /mcp [1].
• Keep tokens out of the file with ${env:NAME}, which Cursor resolves in url and headers [1].
• A server that only takes pre-registered clients needs an auth block with your CLIENT_ID [1].
• Cursor's desktop app connects from your machine, its cloud agents do not. A localhost or VPN server can work in one and fail in the other.

Add the server

The entry above is the whole configuration for an open server. For one that takes an API key, add a headers object, and reference the key through an environment variable so the file can be committed [1]:

{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVER_KEY}"
      }
    }
  }
}

Cursor resolves ${env:NAME} in command, args, env, url and headers, and also knows ${userHome} and ${workspaceFolder} [1]. A project's .cursor/mcp.json is usually committed, so the variable is what keeps a token out of git.

Once it is saved, the server and the tools it offers appear in Cursor's MCP settings, and the agent uses them when they are relevant [1].

Sign in to a server that needs it

For a server that asks for a sign-in, Cursor runs the OAuth flow itself [1]. You do not configure anything for a server that lets clients register themselves, which is most of them.

Some servers only accept clients registered in advance. For those, register an app in the server's developer portal and give Cursor the credentials in an auth block [1]:

{
  "mcpServers": {
    "my-server": {
      "url": "https://mcp.example.com/mcp",
      "auth": {
        "CLIENT_ID": "your-oauth-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "scopes": ["read", "write"]
      }
    }
  }
}

CLIENT_SECRET and scopes are optional. Without scopes, Cursor reads them from the authorization server's metadata [1]. When the portal asks for a redirect URL, register the one for where you will use the server [1]:

Register both if you use both.

How many servers need this? Very few. We read the authorization metadata of 169 real servers that ask for credentials, from our registry census on 9 October 2026: 162 offered Dynamic Client Registration, 33 accepted Client ID Metadata Documents, and only 6 offered neither [2]. Those 6 are the ones that need a CLIENT_ID by hand. Dynamic Client Registration explains both methods.

Works on your machine, fails in cloud agents

The two OAuth redirect URLs above are a clue to something easy to miss. The desktop app makes its requests from your computer. Cursor's web and cloud agents run on Cursor's machines, which is why they get their own redirect URL on cursor.com [1], so their requests to your server come from Cursor's side, not from you.

That splits servers into two groups:

• Reachable only from you: localhost, a server on your VPN, a staging host behind your firewall. These work in the desktop app and cannot work in a cloud agent, because the agent has no route to them.
• Reachable from the internet: these can work in both, as long as nothing in front of them (a firewall, a bot rule, a CDN) turns away requests that do not come from you.

So "it works in Cursor" proves less than it sounds like, and the same is true of every client that runs on your own machine. If anyone else is going to use your server, check it from outside your network.

When it fails to connect

For what the server's own error codes mean, see MCP server errors and MCP server connection failed.

Check it from outside before you share it

Our MCP connection test calls your server from our network, runs the handshake and tools/list, and reports what a stranger on the internet gets back, with a dated URL you can share. That settles the cloud-agent question before you hit it, and it is the same check a teammate's Cursor, Claude or ChatGPT will effectively be making.

The same setup in other clients is in Claude Code, Claude Desktop and ChatGPT, and remote MCP server vs stdio covers whether your server should have a public address at all.

Sources

1. Model Context Protocol (MCP), Cursor docs
2. Dynamic Client Registration, MCP Hunter glossary