How to configure MCP servers in Cursor settings

Open Cursor Settings with Cmd+, (macOS) or Ctrl+, (Windows/Linux). Navigate to the MCP tab in the settings sidebar. This tab shows all configured MCP servers with their connection status (green for connected, red for disconnected/error), the number of tools each server exposes, and any error messages. This is your primary dashboard for MCP monitoring.

Each server in the MCP tab has a status indicator. Green means the server is running and the MCP handshake completed successfully. Yellow may indicate the server is starting up. Red means the server failed to start or the connection was lost. Click on a server to expand its details, which shows the number of tools discovered, the server version, and any error messages.

The primary configuration file for project-specific MCP servers is .cursor/mcp.json in your project root. This file is loaded when Cursor opens the project. You can commit it to git to share the MCP setup with your team. The full configuration supports command, args, env, and cwd fields.

1// .cursor/mcp.json — full configuration options
2{
3  "mcpServers": {
4    "my-server": {
5      "command": "npx",
6      "args": ["-y", "tsx", "src/index.ts"],
7      "env": {
8        "API_KEY": "your-api-key",
9        "DEBUG": "true"
10      },
11      "cwd": "/absolute/path/to/server/directory"
12    }
13  }
14}

For servers you want available in every project, create ~/.cursor/mcp.json in your home directory. Global servers are merged with project-level servers. If both define the same server name, the project-level config takes priority. Use global config for personal utility servers like filesystem, search, or memory.

1// ~/.cursor/mcp.json — global config
2{
3  "mcpServers": {
4    "filesystem": {
5      "command": "npx",
6      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you"]
7    },
8    "memory": {
9      "command": "npx",
10      "args": ["-y", "@modelcontextprotocol/server-memory"]
11    },
12    "brave-search": {
13      "command": "npx",
14      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
15      "env": {
16        "BRAVE_API_KEY": "your-key"
17      }
18    }
19  }
20}

For remote MCP servers using Streamable HTTP transport, use the url field instead of command and args. This connects to servers running on another machine or in the cloud. You can also add headers for authentication.

1{
2  "mcpServers": {
3    "remote-server": {
4      "url": "https://mcp.your-company.com/api"
5    },
6    "authenticated-remote": {
7      "url": "https://mcp.example.com/api",
8      "headers": {
9        "Authorization": "Bearer your-token"
10      }
11    }
12  }
13}

When a server shows red/disconnected status in the MCP tab, click on it to see the error details. Common issues and their solutions: 'Command not found' means the command path is wrong or not in PATH. 'Connection refused' means the server crashed on startup. 'Timeout' means the server took too long to respond to the initialization handshake. For persistent issues, test the server command in your terminal first, then test with MCP Inspector.

1# Test the server command directly in terminal
2npx -y @modelcontextprotocol/server-filesystem /Users/you/projects
3# If this fails, the command is wrong
4
5# Test with MCP Inspector for detailed protocol debugging
6npx -y @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /Users/you/projects