How Cursor handles MCP
Cursor puts MCP servers in the editor's chat and agent workflows. Project installs are easy to share with a repository; global installs are available in every workspace.
Project or global. Project scope keeps the server with the repository; global scope makes it available in every workspace.
Editor-led work where the MCP server belongs with the code.
-a cursorWhere the MCP config lives
The installer writes this file for you. Use the paths below when you want to inspect, edit, or remove a server by hand.
.cursor/mcp.json~/.cursor/mcp.jsonProject paths are relative to the workspace. Global paths are per user. On Windows, ~ means your user folder; use %USERPROFILE% in Explorer or PowerShell. A project config is shared with the team; a global config is personal.
Add a remote server
Start with a server in the MCP directory, or use your provider's endpoint. The examples use https://mcp.example.com/mcp so you can see the shape; replace it with the real URL.
- 01
Find the endpoint
Open a server page and copy its hosted endpoint. Do not use a local command or an npm package name for a remote server; those are different connection types.
Open the MCP directory - 02
Run the installer
Use the project config for a repository-specific server, or the global config for every workspace. The server name becomes
examplein the config.Cursor · project# Add this to Cursor MCP settings: { "mcpServers": { "example": { "type": "http", "url": "https://mcp.example.com/mcp" } } }Cursor · global# Add this to Cursor MCP settings: { "mcpServers": { "example": { "type": "http", "url": "https://mcp.example.com/mcp" } } }If the server page says SSE instead of HTTP, add
--transport sse:SSE variant# Add this to Cursor MCP settings: { "mcpServers": { "example": { "type": "sse", "url": "https://mcp.example.com/mcp" } } }Cursor keeps MCP servers in a project config or a global config. The MCP settings panel shows whether a saved server is enabled.
- 1
Open Cursor Settings
Open Cursor Settings and choose Tools & MCP. The panel lists configured servers and their connection state.
- 2
Add a custom server
Choose Add custom MCP or New MCP Server, depending on the Cursor version. This opens the MCP config for the current project or the user-level config.
- 3
Add the server entry
Add the server under mcpServers. Use the project file for repository-specific tools or the global file for every workspace.
Cursor MCP config{ "mcpServers": { "example": { "url": "https://mcp.example.com/mcp" } } } - 4
Save, enable, and authenticate
Save the file, return to Tools & MCP, and toggle the server on. If Cursor opens a provider sign-in, complete it before using the server.
- 5
Verify the server in chat
Start a new chat and ask which MCP tools are available. A server that is listed but disabled will not expose tools, even when its config is valid.
Project config lives in .cursor/mcp.json. The global file is ~/.cursor/mcp.json. The same server can exist in both places; check both if the expected tools do not appear.
- 1
- 03
Authorize if the provider asks
The first connection may open a browser for OAuth. Sign in with the provider and approve only the scopes you need. If the server uses an API key, create it in the provider's dashboard and add it through the client's auth flow or config.
Never paste a provider token into a project config you will commit. Prefer the client's secret store or a user-level config for credentials.
- 04
Reload and verify
Open the Customize page in Cursor and confirm the server is enabled.
Then ask for a task, not a tool: “Find the open issues assigned to me” or “Summarize the latest release.” The client decides which advertised tool to call.
What changes in the chat
Once the server is connected, its tools appear in the client's tool list. You still talk to the agent normally; MCP is plumbing, not a different chat interface.
“Find the customer notes mentioning the migration and summarize the blockers.”
“Create a draft page with this outline, but do not publish it yet.”
“Check the failed deployment and list the last three changes that touched it.”
“Which MCP tools do you have available for this task?”
If the agent ignores the server, check that the server is enabled and that its tools are approved. Some clients require a per-tool confirmation before the first call.
When it does not connect
The server is missing
Confirm the file exists at the path above, the JSON or TOML is valid, and you restarted the client or opened a new session.
It connects but tools are empty
Enable the server in the client's MCP UI, approve its tools, and check that the provider has not revoked your token.
OAuth keeps reopening
Remove the server from the client, revoke the app's access in the provider's account settings, then add it again.
A project server is ignored
Some clients require you to trust the folder before loading project MCP config. Trust the repository, then start a new session.
What to watch for in Cursor
- Cursor requires you to enable a newly added server on the Customize page.
- Use project scope for repo-specific tools and global scope for personal ones.
- Remote servers may request OAuth the first time Cursor connects.
Remove or reset the server
Remove the server when it is no longer needed, or reset it when a credential or connection state gets stuck.
- Open the Customize page in Cursor and find the server.
- Disable the server first, then remove it or delete its entry from
.cursor/mcp.json. - Reload the window and confirm that the server is gone.
Delete the server entry, restore it from the provider instructions, and complete sign-in again.
Official documentation
Client behavior changes. These links are the source of truth for paths, flags, and approval behavior.