Cursor MCP server setup: how to add any MCP server

An MCP server gives Cursor’s agent tools it did not have: read your docs, query a database, open issues, publish a changelog. Adding one is a few lines of JSON in a file Cursor already knows where to look for. This guide covers that file, the two shapes an entry can take, how to check the server is really connected, and what to do when it is not. Everything here is taken from Cursor’s MCP documentation and its MCP help page, both read on 23 September 2026.

If the server you want is listed in the Cursor Marketplace, you can also install it with one click from Customize and skip the file. The file is what you need for everything else, and it is what a server’s README usually gives you.

Where the config lives

Cursor reads MCP servers from a file called mcp.json, in one of two places:

• Project: .cursor/mcp.json in your project folder. Only that project gets the server. Commit it and your teammates get the same tools.
• Global: ~/.cursor/mcp.json in your home directory. Every project gets the server.

Cursor merges the two files. If the same server name appears in both, the project entry wins. A key written into the project file ends up in git, so either keep keys in the global file or reference an environment variable (below).

A local server: command, args, env

A local server is a program Cursor starts on your machine and talks to over standard input and output (the stdio transport). The entry names the command to run. The field table in Cursor’s docs lists type, command, args, env and envFile:

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

The command must be on your system path or be a full path: npx, node, python and docker are the docs’ examples. A server started with npx needs Node.js installed. envFile loads variables from a file such as .env, and works for local servers only.

A remote server: url and headers

A remote server is already running somewhere and Cursor connects to its URL over Streamable HTTP or SSE. There is nothing to install:

{
  "mcpServers": {
    "my-service": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

headers is optional. Cursor also supports OAuth, for servers that sign you in that way instead of taking a header.

Keep keys out of the file

Cursor resolves variables in command, args, env, url and headers. ${env:NAME} reads an environment variable, and ${workspaceFolder} is the folder that contains .cursor/mcp.json. So a project file can be committed while the token stays in your shell profile:

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

Remote servers do not support envFile, so for them the variable has to be in your shell profile or system environment. Cursor has to see it too: the help page says to restart Cursor after you change your shell profile.

Worked example: Context7

Context7 is a public MCP server from Upstash that fetches current documentation for a library into the agent’s context. It works well as a first server because it has both a local and a remote form, and needs no account to try: its client setup page says the remote endpoint works without a key at a lower, anonymous rate limit, and the README recommends a free key from the Context7 dashboard for higher limits.

The remote form, as Context7 gives it for Cursor:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

The local form runs the npm package @upstash/context7-mcp instead:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
    }
  }
}

Pick one, put it in ~/.cursor/mcp.json (it holds a key), save, and restart Cursor. Trying the remote form without a key? Leave out the headers block. According to its README, the server exposes two tools, resolve-library-id and query-docs. Ask the agent one of the README’s own prompts, such as “Configure a Cloudflare Worker script to cache JSON API responses for five minutes. use context7”, and it should call them.

Check that it is connected

1. Open Customize in the sidebar and go to MCPs. The server should be listed with a toggle.
2. In the chat panel, the tools list at the top shows the server’s tools. Clicking a tool name turns that tool on or off.
3. Ask for something the server does. Cursor uses MCP tools listed under Available Tools when they are relevant; naming the tool in the prompt removes the guesswork.

Approving tools

By default Cursor asks before it runs an MCP tool, and the arrow next to the tool name shows the arguments it is about to send. Read them the first few times: it is the quickest way to see what a server really does. MCP tools follow the same run modes as terminal commands. The help page says that in Cursor 3.6 and above the default is Auto-review mode, under Cursor Settings, Agents, Approvals & Execution: allowlisted tools run straight away and the rest go through a safety classifier. To set the allowlist outside the UI, see permissions.json.

When it does not work

Read the log first. Open the Output panel (Cmd+Shift+U on Mac, Ctrl+Shift+U on Windows and Linux) and choose MCP Logs from the dropdown. Cursor’s docs say it shows server start-up, tool calls and errors, including connection errors, authentication problems and crashes. When a tool call fails in chat, Cursor marks it as failed and the other servers keep working.

The JSON is broken. A trailing comma or a missing brace is the usual cause. Check the file before you blame the server; this runs with plain Node.js:

node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8')); console.log('valid')" ~/.cursor/mcp.json

Also check the wrapper: every server sits inside "mcpServers": { ... }, keyed by a name you choose.

An environment variable is missing. If a server needs ${env:NAME} and you set NAME after Cursor started, Cursor does not have it. Set it in your shell profile and restart Cursor, or for a local server put it in env or an envFile.

The server does not start. For a local server, run the exact command from a terminal (npx -y @upstash/context7-mcp, for example). If it fails there, it fails in Cursor. A “command not found” means the program is not on your path: install it or use the full path in command. For a remote server, check the URL and the header; an authentication error in the log usually means a wrong or expired token.

An update does not show. For npm-based servers, the docs say to remove the server in Customize, run npm cache clean --force and add it again.

Too many tools. Every server adds tools the agent has to choose between. Cursor’s docs do not state a fixed limit today, but they suggest toggling servers off to reduce “tool clutter”. Turn off servers you are not using in this project, or turn off single tools from the tools list in chat.

Security. A local MCP server runs code on your machine with your permissions. Cursor’s docs advise installing servers only from sources you trust, giving them keys with the fewest permissions that work, and reading the code for anything critical.

Second example: Nordva Launch

The same file connects Cursor to Nordva Launch, which gives the agent tools for a product’s waitlist, changelog, feedback, notifications and analytics. It is a remote server; the key is a Launch secret key:

{
  "mcpServers": {
    "nordva": {
      "url": "https://mcp.nordva.dev",
      "headers": {
        "Authorization": "Bearer ${env:NORDVA_API_KEY}"
      }
    }
  }
}

As with any remote server, NORDVA_API_KEY has to be set in your shell profile before Cursor starts, or put the key itself in the global file instead. Or run npx nordva@latest init in your project: it signs you in through the browser, writes your keys to the env file, and installs the server for Cursor and other clients. The free plan has no time limit and needs no card. The full setup, including how to check it with setup_check, is on Connect Cursor to Nordva Launch, and every tool is listed on the MCP server page.

Who should not use Launch for this: if you came here to connect a database, GitHub or a docs server, you do not need Launch at all; the steps above are the whole job. Launch is for someone building a product who wants the agent to run its waitlist, changelog and feedback. If you already have tools for those that you like, keep them.

Using Claude Code as well? The same Context7 server, added with one command, is in How to add an MCP server to Claude Code.