Skip to main content

How to Connect MCP Servers to Cursor

Short answer

Cursor reads MCP servers from a file called mcp.json. Use ~/.cursor/mcp.json to make a server available in every project, or .cursor/mcp.json in a project folder to share it with your team. Each server needs either a command that starts a program on your computer, or a url for a server that runs elsewhere. Save the file and restart Cursor.

Tested withMCP spec 2026-07-28Cursor 3.24 (desktop app)Cursor agent CLI 2026.03.25mcp-server-time 2026.10.19Checked 20 Oct 2026

By Tony LewisHow we test these guides

What you'll have at the end​

A local time server running inside Cursor. The agent can call its tools from chat, and the agent CLI lists them like this:

Tools for time (2):
- convert_time (source_timezone, time, target_timezone)
- get_current_time (timezone)

Before you start

  • Cursor installed. Download it from cursor.com.
  • For the local example: uv, which includes uvx, and Python 3.10 or later. uvx downloads the example server the first time it runs, so you'll need an internet connection.
  • For the remote example: the URL of a remote MCP server. Use your own, or read the steps and come back to it later.
  • Optional: the agent command from Cursor's CLI, for checking your servers from a terminal. If you don't have it, skip the terminal check in step 6.

1. Choose where the config goes​

Cursor merges two config files. Use the global file for servers you want everywhere, and the project file for servers a team shares.

ScopeFileShare it?
Global~/.cursor/mcp.jsonNo. It's yours, and it applies to every project.
Project.cursor/mcp.json in the project rootYes. Commit it to git so teammates get the same servers.

The global file lives in your home folder. On macOS and Linux that's ~/.cursor/mcp.json. On Windows it's %USERPROFILE%\.cursor\mcp.json. If the file doesn't exist, create it.

If a server appears in both files under the same name, Cursor uses the project entry.

Cursor's Customize page can also add servers without editing the file. Open Customize in the sidebar, click MCPs, find the server, and click Add to Cursor. Follow any authentication prompts. Use the file when the server isn't listed, or when you want to set the options yourself.

2. Add a local (stdio) server​

A local server is a program that runs on your computer. Cursor starts it when it needs the tools and stops it later. The config gives Cursor the command to run:

~/.cursor/mcp.json
{
  "mcpServers": {
    "time": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=Europe/London"]
    }
  }
}

The fields are:

FieldRequiredWhat it does
typeYesSet to "stdio" for a local server.
commandYesThe program to start, such as npx, node, python or uvx. It must be on your system path, or you must give its full path.
argsNoThe arguments to pass, as an array.
envNoEnvironment variables for the server, such as an API key.
envFileNoA .env file to load more variables from. Local servers only.

uvx comes with uv and runs a Python package from PyPI. This example runs mcp-server-time, a small server that answers time questions and converts times between time zones. It has no accounts or keys, so it's a safe first test.

The config can use variables. Cursor resolves ${env:NAME} to an environment variable, ${userHome} to your home folder, and ${workspaceFolder} to the project root. You can use them in command, args, env, url and headers.

3. Add a remote server​

A remote server runs somewhere else and Cursor connects to it by URL. Give it a url and leave out command:

mcp.json
{
  "mcpServers": {
    "example-remote": {
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:EXAMPLE_MCP_TOKEN}"
      }
    }
  }
}

Cursor supports remote servers over Streamable HTTP and SSE, and both are given as a URL. The MCP specification lists Streamable HTTP as one of its two standard transports, alongside stdio.

Most remote servers need a token. The example sends one in an Authorization header and reads it from an environment variable, so the token doesn't sit in the file:

export EXAMPLE_MCP_TOKEN="your-token-here"

Put that line in your shell profile (such as ~/.zshrc) so it's set every time you start a terminal. After you change your profile, restart Cursor so it sees the variable. Remote servers don't support envFile, so variables have to come from your shell or system environment.

4. Sign in with OAuth​

Many remote servers use OAuth instead of a token. You sign in through your browser and Cursor keeps the access.

Most servers need nothing extra. Add the url as in step 3, save, and restart. When the server asks for sign-in, Cursor shows an authorization prompt. Follow it in your browser, then return to Cursor.

Some servers need fixed client credentials. Use this when the provider gives you a Client ID, requires you to register a redirect URL, or doesn't support dynamic client registration. Add an auth object next to the url:

mcp.json
{
  "mcpServers": {
    "example-oauth": {
      "url": "https://example.com/mcp",
      "auth": {
        "CLIENT_ID": "${env:EXAMPLE_MCP_CLIENT_ID}",
        "CLIENT_SECRET": "${env:EXAMPLE_MCP_CLIENT_SECRET}",
        "scopes": ["read"]
      }
    }
  }
}

CLIENT_ID is required. CLIENT_SECRET is only needed if the provider uses one. If you leave out scopes, Cursor reads the server's /.well-known/oauth-authorization-server document to find the scopes it supports.

If you use static credentials, register Cursor's callback URLs with the provider. Register both if you sign in from the web and the desktop app:

Where you sign inRedirect URL
Web and Cursor Agentshttps://www.cursor.com/agents/mcp/oauth/callback
Desktop apphttp://localhost:8787/callback

For what happens on the sign-in side, and how to sign in again, see how OAuth sign-in works for MCP servers.

5. Use several servers at once​

Put as many servers in one file as you need. Each one gets its own name and its own entry:

mcp.json
{
  "mcpServers": {
    "time": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-time", "--local-timezone=Europe/London"]
    },
    "example-remote": {
      "url": "https://example.com/mcp"
    }
  }
}

Cursor manages each local server's process for you. If one server fails, Cursor shows the error and the other servers keep working.

6. Restart and check the connection​

  1. Save the file.
  2. Restart Cursor. The servers in mcp.json load at startup.
  3. Open Customize, click MCPs, and check that your server is turned on. Use the toggle beside it to turn a server on or off.
  4. Open a chat and look at the tools list at the top of the panel. Your server's tools should appear there. Click a tool's name to turn that tool on or off.
  5. Ask the agent something the server can answer, such as "What time is it in Tokyo?" For the time server, the agent should call get_current_time or convert_time.

Cursor asks for your approval before it uses an MCP tool. Click the arrow next to the tool's name to see the arguments it's about to send.

To see what's going wrong, open the Output panel (Cmd + Shift + U on macOS, Ctrl + Shift + U on Windows and Linux) and select MCP Logs from the dropdown.

Check from a terminal​

The agent command reads the same config files as the editor. Use it to check a server without opening a chat. From the project folder:

agent mcp list
agent mcp list-tools time

agent mcp list shows each server's status and where its config came from. list-tools shows the tool names and arguments.

Servers defined in a project's .cursor/mcp.json need your approval before they load. Approve one with:

agent mcp enable time

The same commands work inside an interactive session as /mcp list and /mcp list-tools time.

Turning tools off​

Cursor's docs don't publish a limit on how many MCP tools it will use. Every tool adds a name and a description to the context, so keep servers you don't use turned off, and turn off tools you don't need in a server you do use.

Cursor's dynamic context discovery post describes how it handles this. The agent gets the tool names up front and reads the full descriptions only when it needs them. A shorter list still gives the agent fewer choices to get wrong.

Tool approval​

By default, Cursor asks before each MCP tool runs. In Cursor 3.6 and later, the default Auto-review mode under Cursor Settings > Agents > Approvals & Execution lets tools on your allowlist run immediately and sends everything else through a safety classifier. The Allowlist setting keeps the older behavior, where only allowlisted tools run without asking.

Cloud Agents​

Cloud Agents use MCP servers configured in the Cloud Agents dashboard, not the files on your computer. On a Team plan, admins set up shared servers under Dashboard > Plugins & MCPs.

Common problems​

MCP server "time" has not been approved Cursor doesn't load a project's MCP server until you approve it. Run agent mcp enable time in the project folder, using your server's name in place of time.

Connection failed or fetch failed for a remote server Cursor couldn't reach the URL. In the example, the server had stopped running. Check that the URL is correct, including https:// and the path, that the server is running, and that your network allows the connection.

The local server never starts Cursor needs the command to be on your system path, or you need to give its full path. Run which uvx in a terminal, then use the full path in command, such as /Users/you/.local/bin/uvx.

Changes to mcp.json don't take effect Save the file, then restart Cursor. Cursor reads these files when it starts. A syntax error, such as a missing comma or a trailing comma after the last server, stops the file from parsing. Check the JSON with python3 -m json.tool ~/.cursor/mcp.json. It prints the file if it's valid, and points to the error if not.

A server connects but its tools are missing Make sure the server is turned on in Customize > MCPs, and that the tools you want are turned on in the chat panel. If you used agent mcp list-tools, the list there shows what the server actually sends.

For more errors and fixes, see how to fix MCP connection errors.

FAQ​

Where does Cursor store MCP server settings?

In mcp.json. The global file is ~/.cursor/mcp.json and applies to every project. A project file at .cursor/mcp.json applies only to that project, and teammates get it when you commit it to git. If both files define a server with the same name, the project entry wins.

Do I need to restart Cursor after I edit mcp.json?

Yes. Save the file, then restart Cursor. Cursor reads the MCP config when it starts, so a new server won't appear until you restart.

Can I use the same config in the Cursor agent CLI?

Yes. The agent CLI uses the same mcp.json files as the editor. Run agent mcp list to see the servers it found and their status.

Why does Cursor ask me to approve a server from my project?

Project servers can run commands on your computer, so Cursor asks before it loads one. Approve it with agent mcp enable followed by the server name.

How many MCP tools can Cursor use at once?

Cursor's docs don't publish a fixed number. Turn off the servers and tools you don't use, and keep each server focused on one job.