Global vs project mcp.json

Cursor has two mcp.json files. People pick one at random and then post a forum thread titled "MCP not loading."

Cursor's own docs name both:

• Project: .cursor/mcp.json in the repo, for tools that belong to that project
• Global: ~/.cursor/mcp.json in your home directory, for tools you want everywhere

The UI path is the same either way: Settings, Tools & MCP, New MCP Server. That opens a file. Look at the path in the tab before you paste.

What belongs in global

Anything that is about you, not about this app.

Your GitHub account. Your Linear workspace. Context7, if you want current docs in every repo. A Firecrawl key you do not want sitting in git.

I treat the global file like a dotfiles repo: personal, boring, not reviewed in a PR.

What belongs in the project file

Anything that would be wrong in the next repo you open.

This app's Stripe account. This app's Supabase org. A Figma file that only this frontend uses. Playwright, if only this package has a UI to click.

The point of a project file is so a payments repo does not leak Stripe tools into a docs site, and so a contractor cloning the app can share the URL-based servers without inheriting your PAT.

Secrets

Cursor interpolates a few strings in mcp.json:

• ${env:NAME} for an environment variable
• ${userHome} for your home folder
• ${workspaceFolder} for the folder that contains the project .cursor/mcp.json

That last one is easy to miss. It is the project root as Cursor defines it, not "whatever folder I have open."

Firecrawl's install in this directory needs FIRECRAWL_API_KEY. GitHub's hosted Cursor snippet uses a Bearer PAT in headers. Stripe can take a restricted key. None of those belong in a committed project file.

Committing a Firecrawl key in .cursor/mcp.json is how that key is on GitHub by Thursday. Put it in env, or put it in the global file which never gets pushed.

Which file wins

Cursor's public docs describe the two locations. They do not, at least on that page, spell out a merge table. Independent writeups say that if the same server name exists in both, the project file wins for that workspace. That is also how I would design it, and it is how this site talks about it on the Cursor primer.

I still look at Tools & MCP after a reload. Forum posts go both ways: global ignored, project ignored, Windows project file ignored in older 0.46-era builds. The connected row is the ground truth, not a blog's merge rule.

If you define "github" in both files with different URLs, do not guess. Delete one.

A split I actually use

Global:

          {
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}
        

Project, in an app that talks to Stripe:

          {
  "mcpServers": {
    "stripe": {
      "url": "https://mcp.stripe.com"
    }
  }
}
        

Reload. Confirm both rows. Leave Stripe off when you are in a repo that should not touch money.

The rest of the ten follows the same split. Account-wide in home. App-shaped in the repo. Keys out of git.