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.