How to Set Up MCP Tools in Cursor: Step-by-Step Guide

Cursor was one of the first IDEs to ship native MCP support, and it remains one of the best environments for working with MCP-powered tools. But the setup process is not exactly self-explanatory — the documentation is scattered, the config format has quirks, and error messages when something goes wrong are not always helpful.

This guide walks through the entire process from zero to working MCP tools, including the parts that trip people up most often.

What MCP Does in Cursor

Before diving into configuration, it helps to understand what MCP actually changes about how Cursor works.

Without MCP, Cursor's AI assistant (powered by Claude, GPT-4, or other models) can read your files, suggest code changes, and answer questions about your codebase. With MCP, the assistant gains the ability to use external tools — query databases, hit APIs, search the web, run shell commands, interact with browsers, manage files, and anything else an MCP server exposes.

Think of MCP servers as plugins that give Cursor's AI new capabilities. Each server provides a set of tools that the AI can call during a conversation. The AI decides when and how to use them based on your requests.

Step 1: Locate Your MCP Configuration File

Cursor uses a JSON configuration file to know which MCP servers to load. There are two levels of configuration:

Project-Level Configuration (Recommended)

Create a .cursor/mcp.json file in the root of your project. This is the recommended approach because it keeps MCP configuration scoped to the project and can be shared with your team via version control.

mkdir -p .cursor
touch .cursor/mcp.json

Global Configuration

For MCP servers you want available across all projects, use the global configuration file:

• macOS: ~/.cursor/mcp.json
• Linux: ~/.cursor/mcp.json
• Windows: %APPDATA%\Cursor\mcp.json

If the file does not exist, create it. Start with an empty configuration:

{
  "mcpServers": {}
}

Step 2: Add Your First MCP Server

Each MCP server entry in the configuration file needs a name, a command to run, and optionally arguments and environment variables. Here is the general structure:

{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

Let's add a few real servers to see how this works in practice.

Example: Filesystem Server

The filesystem MCP server gives Cursor's AI the ability to read and write files outside the current project directory. This is useful when you need to reference configuration files, access data in other directories, or work across multiple projects.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Documents",
        "/Users/you/Projects"
      ]
    }
  }
}

The paths at the end of the args array are the directories the server is allowed to access. It will not be able to read or write outside these directories.

Example: GitHub Server

The GitHub MCP server lets the AI create issues, read pull requests, search repositories, and manage your GitHub workflow directly from the chat.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Example: Postgres Server

For querying your database directly from the AI chat:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:password@localhost:5432/mydb"
      ]
    }
  }
}

Multiple Servers Together

You can run as many MCP servers as you need. Here is a more complete configuration:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/data"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  }
}

Step 3: Restart Cursor and Verify

After saving your configuration file, you need to restart Cursor for the changes to take effect. A full restart is required — reloading the window is not sufficient for MCP configuration changes.

Once Cursor restarts, open the AI chat (Cmd+L on macOS, Ctrl+L on Windows/Linux) and look for MCP indicators. You can verify your servers are running by checking Cursor's MCP settings panel:

1. Open Cursor Settings (Cmd+, or Ctrl+,)
2. Navigate to the MCP section
3. You should see your configured servers listed with their status

Each server will show a green indicator when connected successfully, or a red indicator with an error message if something went wrong.

Step 4: Test Your Tools

The best way to test is simply to ask the AI to use one of the tools. Here are some test prompts for common servers:

• Filesystem: "List the files in my Documents folder"
• GitHub: "Show me the open issues in my repo"
• Postgres: "Show me the tables in my database"
• Fetch: "Get the contents of https://example.com"

If the tools are working, the AI will call them automatically when relevant. You will see tool calls appear in the chat with their inputs and outputs.

Step 5: Using SSE (Server-Sent Events) Servers

Some MCP servers run as long-lived HTTP services instead of spawned processes. These use the SSE transport type and require a different configuration format:

{
  "mcpServers": {
    "my-remote-server": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Cursor also supports the newer Streamable HTTP transport:

{
  "mcpServers": {
    "my-remote-server": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

SSE servers are useful when you want to run MCP servers as standalone services — perhaps in Docker containers, on remote machines, or shared across multiple IDEs.

Troubleshooting Common Issues

"Server failed to start"

This is almost always one of three things:

1. Node.js is not installed or not in PATH. MCP servers installed via npx require Node.js 18 or later. Run node --version in your terminal to verify.

2. The npx package name is wrong. Double-check the package name. A typo in the args array will cause a silent failure. Try running the full npx command manually in your terminal to see the actual error.

3. Missing environment variables. If a server requires an API key and you did not provide it, the server will start and immediately crash. Check the server's documentation for required environment variables.

Tools Are Not Appearing

If your server shows as connected but the AI is not using the tools:

• Make sure you are using Agent mode in Cursor's AI chat, not the basic Ask mode. MCP tools are only available in Agent mode.
• Try explicitly asking the AI to use a specific tool by name.
• Check that the server actually exposes the tools you expect. Some servers have configuration options that enable or disable specific tools.

"Permission Denied" Errors

On macOS and Linux, if you are running locally installed MCP servers (not via npx), make sure the server binary has execute permissions:

chmod +x /path/to/mcp-server

Server Crashes After First Request

Some MCP servers have dependencies that are not installed automatically. If a server crashes on first use, try installing it globally first:

npm install -g @modelcontextprotocol/server-filesystem

Then update your configuration to use the global installation:

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["/Users/you/data"]
    }
  }
}

Environment Variable Issues

A common mistake is putting environment variables in the wrong place. They must go in the env object inside the server configuration, not in your shell environment:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    }
  }
}

Cursor passes these environment variables to the spawned process. Your shell's environment variables are not automatically inherited by MCP server processes.

Security Considerations

A few things to keep in mind when configuring MCP servers:

• API keys in config files. Your mcp.json file will contain sensitive credentials. Add .cursor/mcp.json to your .gitignore if you are using project-level configuration. For global configuration, the file is already in a non-project directory.

• Filesystem access. Be deliberate about which directories you expose to the filesystem server. Giving it access to your entire home directory means the AI can read any file on your machine. Scope it to the specific directories you need.

• Database access. Consider using a read-only database user for the Postgres MCP server unless you specifically need the AI to write data. This prevents accidental data modification.

• Third-party servers. MCP servers from npm are community-built code that runs on your machine. Review the source code of any server before installing it, especially if it requires elevated permissions or access to sensitive data. Our MCP server security guide covers this topic in detail.

Recommended Starter Setup

If you are just getting started with MCP in Cursor, here is a practical starting configuration that covers the most common use cases:

{
  "mcpServers": {
    "fetch": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Projects"
      ]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

This gives your AI the ability to fetch web content, access files in your projects directory, and maintain persistent memory across conversations. From here, add specialized servers as your workflow demands — browse the AgentSource directory to discover MCP servers organized by use case, or check our review of the best free MCP servers for Claude Desktop for more options that also work with Cursor.