Add an MCP Server to Cursor (.cursor/mcp.json)

MCP gives Cursor’s agent tools beyond your repo — a database, an issue tracker, a docs search. Cursor reads the same mcpServers shape you may know from other clients, from one of two files.

1. Global or project

• ~/.cursor/mcp.json — available in every project you open.
• .cursor/mcp.json — checked into the repo, for tools the whole team needs.

Project config is the better default for anything repo-specific; a teammate who clones gets it without setup instructions.

2. A local server

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"],
      "env": { "LOG_LEVEL": "info" }
    }
  }
}

What it does: launches the server as a child process over stdio. command is required; args and env are optional. ${workspaceFolder} expands to the project root — Cursor also substitutes ${env:NAME}, ${userHome}, and ${pathSeparator} in command, args, env, url and headers.

3. A remote server

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

What it does: connects over HTTP and sends your token as a header. Because the value is ${env:...}, the committed file holds no secret — each developer exports COMPANY_MCP_TOKEN in their own shell. For servers that use OAuth instead, Cursor supports an auth block with CLIENT_ID, CLIENT_SECRET and scopes.

4. Enable and verify

Open Customize in the sidebar and toggle the server on. Then prove it works by naming a tool in chat rather than trusting the green dot:

Use the company-api MCP server to list the open incidents, then summarise the top three.

What it does: forces a real tool call, so a bad token or wrong URL surfaces immediately as an error instead of the agent quietly answering from memory. If the server never appears, check that the JSON parses and that command resolves on your PATH — on Windows, npx usually needs no change, but a bare script path does.

---

Next: write a project rule, see which MCP servers are worth starting with, or generate the file with the MCP config generator.