Cursor reads MCP servers from a project file at .cursor/mcp.json or a global file at ~/.cursor/mcp.json. Local servers use stdio, remote ones use a URL, and by default Cursor asks for approval before running any MCP tool. This guide walks through each part using Cursor's documentation.
Pick a config location. Use the project file for tools tied to one repository, and the global file for tools you want everywhere. You can also install servers from the Customize page or the marketplace.
Local servers over stdio
Cursor starts and manages the process. The fields are type, command, args, env and an optional env file path.
{
"mcpServers": {
"server-name": {
"type": "stdio",
"command": "python",
"args": ["${workspaceFolder}/tools/mcp_server.py"],
"env": { "API_KEY": "${env:API_KEY}" }
}
}
}
The command must be on your PATH or given as a full path. This matches the general MCP advice to use absolute paths, because a client may launch servers from an unexpected working directory.
Remote servers. A remote server takes a URL and optional headers, over SSE or Streamable HTTP.
{
"mcpServers": {
"remote-server": {
"url": "https://api.example.com/mcp",
"headers": { "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}" }
}
}
}
OAuth
If a server supports dynamic registration, Cursor authenticates automatically. If not, you add an auth object with a client ID, an optional client secret and optional scopes. You must register the right redirect URL with the provider. Cursor documents one URL for the web and cloud agents and a localhost callback for the desktop app.
Keep the client ID and secret in environment variables, not in the file.
Tool approval
Cursor asks for approval before running MCP tools by default, and you can expand the prompt to inspect the arguments. Read them. The MCP specification says clients should show tool inputs to the user before calling the server, to avoid accidental or malicious data exfiltration.
Cursor also has run modes. Tools on an allowlist in auto-review mode run without a prompt, and other calls go through a classifier. Treat allowlisting as a trust decision about that specific tool.
Troubleshooting
Toggle a server off in Customize without deleting its config. For errors, open the Output panel and select MCP Logs to see connection, auth or crash messages.
Cursor is also reachable from extension marketplaces such as Open VSX, and Safeguard lists an Open VSX extension for Cursor, Windsurf and Codium on its download page. That is an editor extension, separate from MCP configuration.
A safe first run
Add the server to the project file rather than the global one, so it only exists where you need it. Open the MCP logs, confirm it connects, then give the agent a harmless read-only task and watch the approval prompt. Only after that should you widen use. If the server needs a token, create one limited to the smallest scope the provider offers.
Quick check
Can a remote Cursor server use an env file?
No. Per the docs, the env file option is for stdio servers only. Read secrets from the shell or system environment for remote servers.
Do MCP tools run without asking?
Not by default. Cursor prompts first, unless you allowlist a tool in a run mode that permits it.
Sources
Last reviewed: 19 October 2026.
