Back

How to Add a Remote MCP Server to Cursor

A practical guide to adding a remote MCP server to Cursor with mcp.json: config locations, URL entries, API key and OAuth authentication, team setup, and troubleshooting.

Kelis Shekhaliya

Existing SaaS API connected to AI agents through an MCP layer with documented tools, authentication, testing, and monitoring

TL;DR

To add a remote MCP server to Cursor, add an entry with its <code>url</code> to <code>.cursor/mcp.json</code> for one project or <code>~/.cursor/mcp.json</code> for all projects, then restart Cursor. Pass API keys or bearer tokens through <code>headers</code> using <code>${env:NAME}</code> references, or rely on OAuth, which Cursor handles with PKCE and dynamic client registration. Check MCP Logs in the Output panel when a server does not load.

To add a remote MCP server to Cursor, put an entry with the server's url in an mcp.json file, either .cursor/mcp.json in a project or ~/.cursor/mcp.json for every project, then restart Cursor and check that the server's tools appear. If the server uses API keys or bearer tokens, pass them through headers with an environment variable reference such as ${env:MY_TOKEN}. If it uses OAuth, the URL is usually enough and Cursor walks the user through sign-in.

This guide is for SaaS founders, CTOs, and API teams who run an MCP server, or are about to, and want developers to use it from Cursor. It covers where the configuration lives, what a remote entry looks like, how each authentication method works, how to share a setup with a team, and what to check when the server does not show up.


Why Cursor matters for a SaaS MCP server

Cursor is an AI code editor whose Agent can call MCP tools during a chat. When your product has an MCP server, developers can ask the Agent to read data from your API, create records, or check configuration while they write the integration code, without switching to your dashboard or reading every endpoint reference first.

For a SaaS team, that makes Cursor one of the clients worth documenting next to Claude and ChatGPT. The setup is different from those chat apps: Cursor reads a JSON configuration file on the developer's machine or in the repository, so your setup instructions need to give developers a correct entry to paste, not just a URL. If you also support chat clients, see how to connect a remote MCP server to Claude and ChatGPT.


Before you start

Check these before you write any configuration:

  • The server has a reachable URL. Cursor connects to remote servers by URL. The endpoint must be reachable from the developer's machine.

  • It uses a transport Cursor supports. Cursor supports stdio for local servers and SSE or Streamable HTTP for servers reached by URL. Prefer Streamable HTTP for a new remote server.

  • You know the authentication method. No authentication, a header with an API key or bearer token, or OAuth. Each one changes what goes in the entry.

  • The tools are tested. Confirm discovery and a few tool calls work before you hand the setup to anyone. Our guide to testing an MCP server with MCP Inspector covers this.


Where Cursor reads MCP configuration

Cursor reads MCP servers from two mcp.json locations:

LocationScopeUse it for
.cursor/mcp.json in the project folderThat project onlyA setup you want to share with the team through the repository
~/.cursor/mcp.json in the home directoryEvery project for that userPersonal servers and anything that should not live in a repository

Cursor merges both files. If the same server name appears in both, the project-level entry takes priority. That matters when a developer has a personal entry with the same name as the team one: the project file wins inside that project.

Cursor also offers one-click installs from its marketplace, where a listed server can be added with Add to Cursor and authenticated with OAuth. For your own or a customer-facing server that is not listed there, mcp.json is the standard route.


How to add a remote MCP server step by step

1. Create or open the mcp.json file

Pick the project or global location from the table above. If the file already contains other servers, add the new entry inside the existing mcpServers object instead of replacing the file.

2. Add the server entry

A remote server needs a name and a url:

{
  "mcpServers": {
    "acme": {
      "url": "https://mcp.acme.example/mcp"
    }
  }
}

The key, acme here, is the name developers see in Cursor. Use something short and recognizable, usually your product name.

3. Add authentication if the server needs it

For a header-based method, add a headers object and reference an environment variable rather than pasting the secret. The next section shows each option.

4. Restart Cursor and confirm the tools

Save the file and restart Cursor. The server and its toggle appear under Customize in the sidebar, and the Agent lists the server's tools when they load. If it does not appear, go to the troubleshooting section below.

5. Run a low-impact test

Ask the Agent for a read-only task that clearly needs one of your tools, such as listing a few records. Expand the tool call in the chat to check that it actually called your server and got a real response. A plausible answer without a tool call does not prove the connection works.


Authentication options in Cursor

API keys and bearer tokens in headers

Cursor supports variable interpolation in mcp.json, including in the url and headers fields. Use ${env:NAME} to read a value from an environment variable:

{
  "mcpServers": {
    "acme": {
      "url": "https://mcp.acme.example/mcp",
      "headers": {
        "Authorization": "Bearer ${env:ACME_MCP_TOKEN}"
      }
    }
  }
}

The same pattern works for an API key header such as X-API-Key. Two details trip people up:

  • Remote servers do not support envFile. In Cursor, envFile only works for local stdio servers. For a remote server, set the variable in the shell profile or system environment.

  • Cursor must see the variable. After you add or change it in a shell profile, restart Cursor so it picks up the new value.

OAuth

For a server that uses OAuth, the entry usually needs only the URL. Cursor signs in with the authorization code flow and PKCE, reads the server's protected resource metadata to find the authorization server, and, with dynamic client registration, registers itself as a public client with no client secret. It renews expired access tokens with the refresh token your server issues. If your server returns an expiring access token without a refresh token, users have to sign in again when it expires.

If your authorization server does not support dynamic client registration, or requires redirect URLs to be allowlisted, add a static client in an auth object:

{
  "mcpServers": {
    "acme": {
      "url": "https://mcp.acme.example/mcp",
      "auth": {
        "CLIENT_ID": "${env:ACME_OAUTH_CLIENT_ID}",
        "scopes": ["read", "write"]
      }
    }
  }
}

Cursor documents fixed redirect URLs for this case: http://localhost:8787/callback for the desktop app and https://www.cursor.com/agents/mcp/oauth/callback for the web and Cursor Agents. Register both on your OAuth app if users sign in from both. If your provider only issues refresh tokens for a scope such as offline_access, include it in scopes.

Which method should you offer? OAuth gives each user their own permissions and avoids long-lived keys in local environments. Header credentials are simpler for internal teams and early testing. Our guide to API authentication for MCP compares API keys, bearer tokens, and OAuth in more depth.


Sharing a Cursor MCP setup with your team

A project-level .cursor/mcp.json can be committed to the repository so everyone who opens the project gets the same server. Keep it safe to commit:

  • Put only the URL, header names, and ${env:...} references in the file, never real tokens or keys.

  • Document which environment variables each developer must set, and how to get a credential.

  • Use a server name that will not clash with personal entries, since the project entry overrides a global one with the same name.

For larger organizations, Cursor also has admin controls. Team admins can configure shared MCP servers in the Cursor dashboard, which Cloud Agents can use, and Enterprise admins can maintain an MCP allowlist that approves remote servers by URL pattern. If your customers are enterprises, tell them the exact endpoint URL so their admins can approve it.


Using your tools in Cursor chat

Once connected, the Agent uses MCP tools automatically when they are relevant, and developers can also ask for a tool by name. By default, Cursor asks for approval before it runs an MCP tool, and the user can expand the call to see its arguments. Approval settings can let allowlisted tools run without asking.

Because the Agent decides from names and descriptions which tool to call, the quality of your tool surface shows up quickly in Cursor. Clear names, precise descriptions, and a focused set of tools make the Agent pick the right one. See how to choose which API endpoints to expose as MCP tools.


Troubleshooting a remote MCP server in Cursor

Check the MCP logs first

Open the Output panel (Cmd+Shift+U on Mac, Ctrl+Shift+U on Windows and Linux) and select MCP Logs. The logs show server initialization, tool calls, and errors, which is usually enough to tell a configuration problem from an authentication or server problem.

The server does not appear

Check that the JSON is valid, the entry sits inside mcpServers, and the file is in .cursor/mcp.json or ~/.cursor/mcp.json. Then restart Cursor. Also check the server is enabled under Customize, since disabled servers do not load.

Authentication fails

Confirm the header name matches what your server expects, the environment variable is set where Cursor can read it, and Cursor was restarted after it was set. For OAuth, check that the redirect URLs are registered and the requested scopes exist.

The server connects but its tools are not used

Confirm the tools are toggled on in the tools list, then ask for the tool by name. If the Agent still prefers other tools, review your tool names and descriptions, and test the same calls outside Cursor to rule out a server-side error.

The server only runs on localhost

A URL on localhost works for the developer running it, but not for customers or teammates. Host the server on a public endpoint before you share setup instructions.


Adding a 0mcp server to Cursor

If your MCP server is hosted on 0mcp, you do not need to write the entry by hand. Publish a server version, open Setup, and select Cursor. 0mcp generates the mcpServers entry with your hosted endpoint and credential mapping. Add it to .cursor/mcp.json or ~/.cursor/mcp.json, set the environment variables Setup lists, and restart Cursor. Secret values stay in environment variables, not in the JSON file. The 0mcp Cursor setup guide has the details.


Final checklist

  • The server URL is reachable and uses Streamable HTTP or SSE.

  • The entry is in the right mcp.json for its scope.

  • Secrets are passed with ${env:...} references, not written into the file.

  • OAuth redirect URLs are registered if you use a static client.

  • Cursor was restarted and the server shows as enabled.

  • A read-only test call reached your server and returned real data.

  • Team setup instructions list every variable a developer must set.

FAQ

01Where is the MCP config file in Cursor?+

Cursor reads <code>.cursor/mcp.json</code> in a project folder for that project and <code>~/.cursor/mcp.json</code> in your home directory for all projects. Both files are merged, and the project entry wins when two servers share a name.

02How do I pass an API key to a remote MCP server in Cursor?+

Add a <code>headers</code> object to the server entry and reference an environment variable, for example <code>"Authorization": "Bearer ${env:MY_TOKEN}"</code>. Set the variable in your shell profile or system environment and restart Cursor. Remote servers do not support <code>envFile</code>.

03Does Cursor support OAuth for MCP servers?+

Yes. Cursor uses the authorization code flow with PKCE and supports dynamic client registration. If your provider needs a fixed client, add an <code>auth</code> object with <code>CLIENT_ID</code>, an optional <code>CLIENT_SECRET</code>, and <code>scopes</code>.

04Should a remote MCP server use SSE or Streamable HTTP with Cursor?+

Cursor supports both for servers reached by URL. Streamable HTTP is the current MCP transport for remote servers, so prefer it for a new server and keep SSE only for existing setups.

05Why don't my MCP tools show up in Cursor?+

Check that <code>mcp.json</code> is valid and in the right location, restart Cursor, and make sure the server is enabled under Customize. Then open the Output panel and select MCP Logs to see connection or authentication errors.

06Can I commit .cursor/mcp.json to git?+

Yes, Cursor suggests committing the project file so teammates get the same tools. Keep only the URL, header names, and <code>${env:...}</code> references in it, never real credentials.