Global or project: which to choose

Cursor gives you two places to put a server, and it's the choice that matters most.

  • Global (~/.cursor/mcp.json, in the user folder): the server is available in all your projects. Suited to tools you always use, like web search.
  • Project (.cursor/mcp.json inside the project folder): the server applies only there. Suited to a filesystem server pointed at that project's files, or when you work in a team and want to share the same configuration. If the same server is in both, the project one wins.

How to do it

From here on the file has the same form in both cases; only where you put it changes.

  1. Enable MCP in the settings. Open Cursor's settings and search for "MCP": check that the option to enable servers is on. In some installations it's off by default, and it's the number-one reason why "nothing works".
  2. Add the server in the file. The operative syntax:
{
  "mcpServers": {
    "documents": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects/site"]
    }
  }
}

documents is the name you choose; the last value is the folder the server will be able to see. For a project server, point it to that project's folder.

  1. Save and check the indicator. Cursor rereads the file and shows the server's status: a green dot (or similar) signals it's connected. If it stays red or grey, something in the configuration is off.
  2. Use it in chat. Open Cursor's assistant and ask it to use the tool ("read the project files and..."). If it's connected, it'll use it.

A concrete example

Davide uses Cursor for a website he's building and wants the assistant to read the project files without him opening them one by one. He creates a .cursor/mcp.json file inside the site's folder, pastes the filesystem server block pointed at that folder, and in settings checks that MCP is enabled.

He saves and sees the green dot next to the server. From that moment, when he asks the assistant "check whether the contacts page has the right form", Cursor reads the project's real files and replies on the actual content, instead of guessing. Having set it as a project server, that connection applies only to this site and doesn't carry over into the others.

When it does NOT work (and how to fix it)

If the servers don't start at all

Check the switch first: if the option to enable MCP servers is off in the settings, no server loads, however well the file is written. Turn it on and recheck.

If the indicator stays red

The file has an error. Cursor won't connect a server if the JSON (the bracket-and-comma format) isn't valid. Have the content validated by Cursor's own assistant ("is this JSON correct?") and fix the flagged line.

If some tools disappear

Cursor has a cap on the number of tools active together (around forty): beyond that threshold, the assistant silently stops seeing some tools. If you've connected many servers, disable the ones you don't need for that job, so you stay under the limit.

A tip from someone who really uses it

Use project servers for the files and keep only the generic tools global. That way, opening a project, the assistant sees exactly that job's files and nothing extraneous. It's also safer: each project stays a separate box, and you don't risk the AI digging into a different client's folders.

Frequently asked questions

Do I have to restart Cursor after adding a server?

Usually Cursor rereads the file on save and updates the indicator without a restart. If, however, you see no changes, closing and reopening the app almost always solves it: it's the first thing to try when something stays stuck.

Can I share the MCP configuration with my team?

Yes, and it's one of the advantages of the project file: by putting .cursor/mcp.json in the shared project folder, whoever works with you has the same servers. Be careful not to put keys or passwords in it: those should be managed separately.

Is Cursor's configuration the same as that of other editors?

The file's form is similar but not identical across different tools: the position and sometimes the name of the main entry change. A configuration that works in Cursor doesn't paste as-is elsewhere: always check the format required by the tool you're using.