How to connect MCP servers to Cursor

Create a .cursor directory in your project root and add an mcp.json file. This is the project-level configuration — it only applies to this project and can be committed to git so your team shares the same MCP setup. The top-level key is mcpServers, and each entry maps a server name to its command configuration.

1// .cursor/mcp.json
2{
3  "mcpServers": {
4    "filesystem": {
5      "command": "npx",
6      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
7    }
8  }
9}

You can configure multiple MCP servers in a single file. Each server gets a unique name as its key. Cursor launches all configured servers when it opens the project. Common servers include filesystem for file access, GitHub for repository management, and custom servers for your project's specific needs.

1// .cursor/mcp.json with multiple servers
2{
3  "mcpServers": {
4    "filesystem": {
5      "command": "npx",
6      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
7    },
8    "github": {
9      "command": "docker",
10      "args": ["run", "-i", "--rm",
11        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
12        "ghcr.io/github/github-mcp-server"],
13      "env": {
14        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
15      }
16    },
17    "my-custom-server": {
18      "command": "npx",
19      "args": ["-y", "tsx", "/path/to/my-server/src/index.ts"]
20    }
21  }
22}

Use the env field to pass environment variables (API keys, database URLs, configuration values) to MCP servers. These variables are set in the server's process environment when Cursor launches it. Never hardcode secrets in the args array — always use env.

1{
2  "mcpServers": {
3    "database": {
4      "command": "npx",
5      "args": ["-y", "@modelcontextprotocol/server-postgres"],
6      "env": {
7        "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/mydb"
8      }
9    }
10  }
11}

For servers you want available across all projects (like filesystem or GitHub), create a global configuration file at ~/.cursor/mcp.json. Global servers are merged with project-level servers. If both files define the same server name, the project-level configuration takes precedence.

1// ~/.cursor/mcp.json (global — available in all projects)
2{
3  "mcpServers": {
4    "filesystem": {
5      "command": "npx",
6      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you"]
7    },
8    "brave-search": {
9      "command": "npx",
10      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
11      "env": {
12        "BRAVE_API_KEY": "your-brave-api-key"
13      }
14    }
15  }
16}

After creating or editing the MCP configuration, fully restart Cursor (Cmd+Q then reopen, or use the Developer: Reload Window command). Then verify the connection: open Cursor Settings (Cmd+,), navigate to the MCP tab, and check that your servers show a green 'Connected' status. If a server shows red or disconnected, click on it to see error details.

Open a new Cursor chat (Cmd+L) or Composer (Cmd+I) and ask a question that requires an MCP tool. For example, if you connected the filesystem server, ask 'List the files in /path/to/directory'. Cursor will show when it is using an MCP tool and display the tool's response. In Composer agent mode, Cursor can chain multiple MCP tool calls autonomously.

1// Example prompts to test MCP tools in Cursor:
2// With filesystem server: "List all TypeScript files in /Users/you/project/src"
3// With GitHub server: "Show me the open issues on my-org/my-repo"
4// With custom server: "Get the weather in Tokyo"