MCP & Agent Interoperability · MCP Client Configuration
Configuring MCP Servers in Cursor: A Step-by-Step Guide
Where Cursor's MCP configuration files live, how global and project-level config merge, and the security questions worth asking before adding a server — local or remote.
Published 2026-06-15 · 12 min read
Editorial draft: this article remains noindex until its material claims are mapped to page-level source receipts and reviewed.
Direct answer
Cursor reads MCP server configuration from two possible locations that it merges together: a global config at ~/.cursor/mcp.json (or the equivalent Windows path) that applies across all projects, and an optional project-specific .cursor/mcp.json in a given repository root that adds servers scoped to that project. Both are edited either directly as JSON or through Cursor's Settings > Tools & MCP interface, which offers a 'New MCP Server' action that opens the same file. A local server is configured with a command and args (typically invoking it via npx or a local binary); a remote server is configured with a url and optional headers for authentication, with no command needed since Cursor connects to it over HTTP directly.
Where the configuration lives
Cursor supports two MCP configuration files, and loads both when present: a global file at ~/.cursor/mcp.json on macOS and Linux (or the corresponding %USERPROFILE%\.cursor\mcp.json on Windows) that applies to every project, and an optional project-scoped .cursor/mcp.json placed in a specific repository's root that adds servers only for that project. When both exist, Cursor merges the server lists rather than one overriding the other, which is useful for keeping broadly-used servers (a general web-search tool, for instance) global while keeping project-specific integrations (a particular project's database) scoped to that repository only.
Adding a local server
A locally-run MCP server is defined with a command (the executable to run, commonly npx for a Node-based server) and args (the arguments passed to it), plus an optional env block for environment variables the server needs — an API key, for instance. Cursor's Settings > Tools & MCP panel includes a 'New MCP Server' action that opens the mcp.json file directly at the right place to add a new entry, which is often faster than hand-editing the file from scratch for a first-time setup.
Adding a remote server
A remote MCP server, reachable over HTTP, is configured with a url pointing at the server's endpoint and an optional headers block for authentication — commonly a bearer token. No command or args are needed for a remote server, since Cursor connects directly over the network rather than spawning a local process.
Security questions to answer before adding any server
- For a remote server, confirm the endpoint uses TLS and requires real authentication — an unauthenticated remote MCP server is reachable by anyone who finds its URL, not just Cursor.
- For any server holding a credential (an API key in the env block, a bearer token in headers), scope that credential to the minimum access the server's tools actually need, not a broadly-permissioned one reused elsewhere.
- For a community-published server added via npx, review its source and maintenance status before pointing it at anything containing real project data — see this site's MCP security best practices guide for the fuller checklist.
- Prefer project-scoped .cursor/mcp.json for anything holding project-specific or sensitive credentials, rather than the global config, so a credential doesn't silently apply across every project on the machine.