Cursor MCP Setup: mcp.json, Remote URLs, Headers and Env
Updated 2026-11-18
To set up an MCP server in Cursor, add it to .cursor/mcp.json in your project or ~/.cursor/mcp.json in your home directory. A local server uses command and args. A remote server uses url, plus optional headers. Cursor reloads the entry and lists the server's tools in chat.
Pick a config file
Cursor reads MCP servers from two places:
| File | Scope | Use it for |
|---|---|---|
.cursor/mcp.json | Current project | Servers the whole team uses with this repo |
~/.cursor/mcp.json | All projects | Personal servers you want everywhere |
Create the file if it does not exist. Do not put secrets in the project file if you commit it. Use environment variables instead, as shown below.
Add a remote server with url
A remote server is reached over HTTP. The two fields to know are:
url(required): the server endpoint, usually ending in/mcp.headers(optional): key-value pairs sent with each request, for example an API key.
{
"mcpServers": {
"example-remote": {
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer ${env:EXAMPLE_API_TOKEN}"
}
}
}
}
Set EXAMPLE_API_TOKEN in your shell environment before starting Cursor. The token is then never written to the file.
If the server uses OAuth, you do not need headers. Cursor supports the OAuth authorization code flow with PKCE and reads protected resource metadata. With dynamic client registration, Cursor registers itself as a public client with no secret. Expired access tokens are renewed with a refresh token when the server issues one. Otherwise you sign in again.
Some providers need fixed credentials. For those, add an auth object with CLIENT_ID (required), CLIENT_SECRET (optional) and scopes (optional). These values can also use interpolation, for example ${env:MCP_CLIENT_ID}.
Add a local server with command
A local (stdio) server is a program Cursor starts on your machine. The fields are:
type:"stdio". The Cursor docs list it as required for this form.command(required): the executable. It must be on yourPATHor given as a full path.args(optional): an array of arguments.env(optional): environment variables for the server process.envFile(optional): a path to an env file. It works for stdio only, not for remote servers.
{
"mcpServers": {
"example-local": {
"type": "stdio",
"command": "npx",
"args": ["-y", "example-mcp-server@1.2.3"],
"env": {
"EXAMPLE_API_KEY": "${env:EXAMPLE_API_KEY}"
}
}
}
}
The example pins the package to a version, so a later release cannot change what runs on your machine without you noticing. See the MCP server security checklist for why that matters.
Variables you can use
Cursor resolves these in command, args, env, url and headers:
${env:NAME}: an environment variable.${userHome}: your home folder.${workspaceFolder}: the project root, meaning the folder that contains.cursor/mcp.json.${workspaceFolderBasename}: the project folder name.${pathSeparator}and${/}: the OS path separator.
{
"mcpServers": {
"project-files": {
"type": "stdio",
"command": "node",
"args": ["${workspaceFolder}/tools/mcp-server.js"]
}
}
}
Install from the marketplace instead
You do not have to edit JSON. The Cursor Marketplace has an "Add to Cursor" button on each entry. It installs the server and starts OAuth where the server needs it. Community servers are also listed on cursor.directory. Manual setup in mcp.json works for everything else, including servers you find in the list of MCP servers that work with Cursor.
Enable, disable and check a server
Open Customize in the sidebar, find the server and use its toggle. According to the Cursor docs, disabled servers do not load and do not appear in chat. Turn off servers you are not using. Fewer servers means fewer tools in the model's context and less to review.
When a server is connected, ask the agent to use one of its tools by name to confirm it works.
Troubleshooting
- Server does not start. Run the
commandandargsin a terminal. If that fails, Cursor cannot start it either. Check that the executable is on yourPATH. - Variable is empty.
${env:NAME}reads an environment variable. Make sure it is set in the environment Cursor was started from, then restart Cursor. - 401 from a remote server. Check the
Authorizationheader, or let OAuth run by removing the header. - Endpoint is down. Some listed servers are offline. Agents Index probes remote endpoints daily and shows the result on each listing. See how we probe.
If you are new to the protocol, read what an MCP server is first. Using another editor? See the guides for VS Code and Claude Code.
Sources
FAQ
Where is the Cursor MCP config file?
Use .cursor/mcp.json in your project for project-specific servers, or ~/.cursor/mcp.json in your home directory for servers available in every project.
How do I add a remote MCP server to Cursor?
Add an entry to mcp.json with a url field, and an optional headers object for API keys. If the server uses OAuth, Cursor starts the sign-in flow when you connect.
Can I use environment variables in Cursor mcp.json?
Yes. Cursor resolves ${env:NAME} in command, args, env, url and headers. It also supports ${userHome} and ${workspaceFolder}.
How do I turn an MCP server off in Cursor?
Open Customize in the sidebar, find the server and use its toggle. Cursor's docs say disabled servers do not load or appear in chat.