How to use MCP servers in Cursor: setup and fixes

To use an MCP server in Cursor, either install it in one click from Customize, then MCPs, or add it to an mcp.json file: .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project. A local server is a command with args, a remote one is a url. Save, restart Cursor, and the agent calls the server's tools when they fit your request. In Cursor 3.6 and later the default Auto-review mode runs allowlisted tools straight away and sends the rest to a safety classifier. Below is each route step by step, the config fields that matter, and what to check when a server won't load.

Where does Cursor look for MCP servers?

In two files, according to Cursor's MCP help page (checked November 2026). The project file is for tools that belong to one codebase, and the page suggests committing it to git so teammates get the same tools. The global file is personal and applies everywhere.

Project  .cursor/mcp.json     (in the project folder, can be committed)
Global   ~/.cursor/mcp.json   (in your home folder, every project)

The same page says both files are merged, and if the same server name appears in both, the project-level config takes priority. Servers you install from the marketplace show up in Customize next to the ones from your files. Cursor's Customize page docs describe it as the one place for plugins, skills and MCPs, filterable by user, workspace or team scope.

If you are new to the protocol itself, the MCP explainer covers hosts, clients, servers and transports in plain terms. Here, Cursor is the host.

How do you install an MCP server in one click?

For servers listed in the Cursor Marketplace, there is no JSON at all. The steps from Cursor's help page (checked November 2026):

1. Open Customize in the sidebar.
2. Click MCPs.
3. Browse available servers or search for the one you want.
4. Click Add to Cursor next to the server.
5. Follow the authentication prompts if required.

Cursor's MCP reference points to the Cursor Marketplace for official plugins and to cursor.directory for community plugins and MCP servers. Anything not listed there, including your own servers, goes in mcp.json.

Local or remote: which kind of server do you have?

Look at what the server's README tells you to paste. A command such as npx -y some-package means a local server that Cursor starts on your machine. An https:// address means a remote server that someone else runs. The MCP reference lists three transports: stdio for local servers, and SSE and Streamable HTTP for servers deployed at a URL.

How do you add a local MCP server to mcp.json?

1. Create .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project.
2. Add an entry under mcpServers with a name, the command that starts the server, its args and any env values it needs.
3. Save the file and restart Cursor.
4. Open Customize, then MCPs, and check the server is there and switched on.

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

The MCP reference lists the stdio fields: type ("stdio"), command, which must be available on your system path or contain its full path, args, env, and envFile, a path to an environment file such as .env. A second server is a second key inside the same mcpServers object, not a second mcpServers block.

Keep secrets out of the file

A committed project file should not hold keys. Cursor resolves variables in command, args, env, url and headers, per the MCP reference. The useful ones are ${env:NAME} for an environment variable, ${userHome}, and ${workspaceFolder}, which is the folder that contains .cursor/mcp.json. This is the reference's own example:

{
  "mcpServers": {
    "local-server": {
      "command": "python",
      "args": ["${workspaceFolder}/tools/mcp_server.py"],
      "env": {
        "API_KEY": "${env:API_KEY}"
      }
    }
  }
}

Each teammate then sets API_KEY in their own shell, and the file can be shared as is. The help page adds one catch: variables from your shell profile have to be available to Cursor, so restart Cursor after you change the profile.

How do you add a remote MCP server by URL?

A remote entry needs only a url. What else it needs depends on how the server signs you in.

OAuth with dynamic client registration.Add the URL and nothing else. The MCP reference says Cursor signs in with the authorization code flow with PKCE, reads the server's protected resource metadata to find its authorization server, and with dynamic client registration registers itself as a public client with no client secret. From the CLI, agent mcp login <identifier> authenticates with a server configured in your mcp.json.

A fixed token.If the server's docs give you an API key or bearer token instead, send it as a header and read it from the environment:

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

OAuth with a fixed client ID. Some providers do not support dynamic registration or want a whitelisted redirect URL. For those, the reference documents an auth object with CLIENT_ID (required), CLIENT_SECRET (only for confidential clients) and scopes. If you leave scopes out, Cursor discovers them from the server's /.well-known/oauth-authorization-server metadata.

{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "${env:MCP_CLIENT_ID}",
        "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}"
      }
    }
  }
}

Register these redirect URLs with the provider's OAuth app. The reference says to register both if people sign in from the web and the desktop app.

Web and Cursor Agents  https://www.cursor.com/agents/mcp/oauth/callback
Desktop app            http://localhost:8787/callback

Two details from the same page save time later. If a provider issues refresh tokens only for a scope such as offline_access, add that scope to auth.scopes, or you will be asked to sign in again every time the access token expires. And Cloud Agents keep their own MCP sign-ins on Cursor's servers, so signing out on your machine does not sign them out.

How do you use MCP tools in Cursor chat?

You mostly don't have to do anything. The MCP reference says Cursor automatically uses MCP tools listed under Available Tools when relevant, including in Plan Mode. You can also ask for a tool by name, which helps when two servers offer similar tools.

• Turn single tools off. Per the help page, click the tool name in the tools list at the top of the chat panel.
• Turn a whole server off. Open Customize, find the server and use the toggle. Disabled servers won't load or appear in chat.
• Check the arguments. When Cursor asks for approval before an MCP call, click the arrow next to the tool name to see the arguments it is about to send.

How often you get asked depends on your Run Mode, set in Settings > Agents > Approvals & Execution. Cursor's Run Modes page (checked November 2026) lists three: Auto-review, where allowlisted calls run immediately and other calls go to a classifier; Allowlist, where only actions in your allowlist run without approval; and Run Everything, where every tool call runs automatically. Since Cursor 3.6, Auto-review is the default. The page is blunt that Auto-review "is not a security boundary". For a server that spends money or writes to a production system, keep approvals on or describe the calls you always want to review in permissions.json, as the page explains.

Does the Cursor CLI use the same MCP servers?

Yes. Cursor's CLI MCP docs (checked November 2026) say MCP in the CLI uses the same configuration as the editor, so anything in your mcp.json files works in agent too. It adds commands that are handy for checking a setup without opening the editor:

$ agent mcp list                    # servers, status, source, transport
$ agent mcp list-tools <identifier>  # one server's tools and parameters
$ agent mcp login <identifier>       # sign in to a server from mcp.json
$ agent mcp enable <identifier>
$ agent mcp disable <identifier>

The same page documents --approve-mcps to skip the approval prompts for all MCP servers in a run. That suits scripted jobs on servers you trust, and nothing else.

Why is my MCP server not working in Cursor?

Work through these in order. The logs in step 2 usually name the problem.

1. Restart Cursor after any change to mcp.json or to your shell profile.
2. Read the logs. Open the Output panel (Cmd + Shift + U on Mac, Ctrl + Shift + U on Windows and Linux) and select MCP Logs from the dropdown. Per the MCP reference, they show server initialization, tool calls and errors, including connection and authentication problems.
3. Validate the JSON. One trailing comma breaks the whole file, and a second mcpServers block silently replaces the first, so servers vanish.
4. Check the command. command must be on your system path or be a full path. Run the same command in a terminal; if it fails there, it fails in Cursor.
5. Check the environment. A key you exported in your shell profile is only visible after Cursor restarts.
6. Remove and re-add it.The help page's restart step for a stuck server is to remove it from Customize > MCPs and add it again.

To pick up a new version of an npm-based server, the MCP reference says to remove it from Customize, clear the npm cache and re-add it.

$ npm cache clean --force

On a company machine, the MCP reference describes admin controls that can block a server you configured correctly: an MCP allowlist of approved commands and URLs, and per-server network modes. The help page notes that when an admin enables MCP Network Controls, Windows cannot run the sandbox, so affected stdio servers don't start and MCP Logs say the server requires sandboxing. The fix there is an admin adding a Command entry with the No sandbox network mode, not anything in your own file.

A worked example: adding Goro to Cursor

Goro is a remote MCP server that signs you in with OAuth 2.1 and supports dynamic client registration, so its entry is just the URL. Put it in the global file if you want it in every project. Use the full /mcp path; the bare host serves the web app, not the MCP endpoint. There is no API key to paste for the MCP connection.

{
  "mcpServers": {
    "goro": {
      "url": "https://mcp.usegoro.ai/mcp"
    }
  }
}

Restart Cursor, sign in when asked (or run agent mcp login goro from the CLI), and the agent gets a catalog of real-world tools: web and news search, page scraping, social platform data, maps, people and company enrichment, plus image, video and voice generation. The agent sees the price before each call and reports which tool ran and what it cost.

In a coding session that is useful for jobs outside your repo. Ask the agent to audit the live pages of the site you are working on and fix what it finds, and it can call website audit, from $0.12 per page. Ask it to read the changelogs of three libraries before an upgrade, and web page scrape returns the cleaned text, from $0.005970 per result.

Be honest about whether you need it. Cursor's own agent already makes Fetch calls (the Run Modes page lists them next to shell and MCP calls), so reading one docs page needs nothing extra. A gateway pays off when you would otherwise add a separate server, account and bill for each data source. Running tools needs a plan, from $19 a month with $25 of tool credit included; details are on the pricing page. If you also use Claude Desktop, the Claude Desktop setup guide covers the same server there.