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

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

Cursor is one of the most popular AI code editors, and it has built-in support for MCP (Model Context Protocol). This means you can connect Cursor to GitHub, databases, Docker, and dozens of other tools — all without leaving your editor.

This guide walks you through the exact setup process, from creating your first config file to troubleshooting common errors.

What MCP Does in Cursor

Without MCP, Cursor's AI can only see your open files. With MCP, it can:

• Read and create GitHub issues and PRs without opening a browser
• Query your database to understand your data while writing code
• Manage Docker containers to spin up dev environments
• Search documentation for up-to-date API references
• Access Figma designs to implement UI components accurately

MCP tools are available in Cursor's Agent mode (the composer panel). They don't work in the basic chat or inline edit modes.

Prerequisites

• Cursor (version 0.45 or later — MCP support was added in early 2025)
• Node.js 18+ installed (for npx-based servers)
• Docker (optional, for Docker-based servers)

Step 1: Create Your MCP Config File

Cursor looks for MCP configuration in two places:

Global Config (applies to all projects)

~/.cursor/mcp.json

Project Config (applies to one project)

your-project/.cursor/mcp.json

Create the file and directory if they don't exist:

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

Step 2: Add Your First Server

Let's start with the GitHub MCP server. Open ~/.cursor/mcp.json and add:

json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUBPERSONALACCESSTOKEN": "ghpyourtokenhere"
      }
    }
  }
}

To get a GitHub token:

1. Go to github.com → Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens
2. Create a new token with repo scope
3. Copy the token and paste it in the config

Step 3: Verify the Connection

1. Open Cursor
2. Go to Settings → MCP (or Cursor Settings → Features → MCP)
3. You should see your GitHub server listed with a green status indicator
4. If the indicator is red or yellow, check the error message

Alternatively, open the Agent (Composer) panel and look for the tools icon. Your MCP tools should appear there.

Step 4: Test It

Open the Composer in Agent mode and try:

> "List my open GitHub issues in this repo"

Cursor will use the GitHub MCP server to fetch your issues. You'll see a tool approval prompt before it runs.

Recommended MCP Servers for Cursor

Here's a practical config with the most useful servers for coding:

json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUBPERSONALACCESSTOKEN": "ghpyour_token"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/your/projects"
      ]
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:pass@localhost:5432/mydb"
      ]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

What each server does:

• GitHub — PR reviews, issue management, code search
• Filesystem — Read/write files outside your project
• PostgreSQL — Query your database while coding
• Context7 — Up-to-date docs for 9,000+ libraries (no more outdated API suggestions)
• Sequential Thinking — Better reasoning for complex debugging

For more options, see our best MCP servers for developers guide.

Transport Types: stdio vs Streamable HTTP

Cursor supports two ways to connect to MCP servers:

stdio (Default)

The server runs as a local process. This is what the examples above use. It's simpler, faster for local tools, and works offline.

json
"my-server": {
  "command": "npx",
  "args": ["-y", "package-name"]
}

Streamable HTTP (Remote Servers)

For servers running on a remote machine or cloud service:

json
"my-remote-server": {
  "url": "https://mcp.example.com/v1/mcp",
  "headers": {
    "Authorization": "Bearer your-token"
  }
}

Streamable HTTP replaced the older SSE transport. If you see guides mentioning SSE, they're outdated — use Streamable HTTP instead.

Common Errors and Fixes

"Server failed to start"

Cause: Usually a missing dependency or wrong Node.js version. Fix:

1. Open terminal and run the npx command manually to see the actual error:

bash
npx -y @modelcontextprotocol/server-github

1. If it says "node not found," install Node.js 18+
2. If it fails with a dependency error, try clearing the npx cache:

bash
npx clear-npx-cache

"Tools not appearing in Agent mode"

Cause: MCP tools only work in Agent mode, not Chat mode. Fix: Make sure you're using the Composer panel in Agent mode. Click the mode selector in the Composer and switch to "Agent."

"Config file not being read"

Cause: Wrong file location or invalid JSON. Fix:

1. Verify the file is at ~/.cursor/mcp.json (global) or .cursor/mcp.json (project)
2. Validate your JSON — a missing comma or bracket breaks everything
3. Use a JSON validator: paste your config at jsonlint.com

"Server connected but times out"

Cause: Some servers take time to initialize, especially Docker-based ones. Fix: Cursor has a default timeout. For slow servers, you may need to restart Cursor and try again. Some servers also have startup flags to preload resources.

"Too many tools" warning

Cause: Each MCP server exposes multiple tools. With 5+ servers, you might hit Cursor's tool limit. Fix: Cursor supports tool filtering. In settings, you can enable/disable individual tools from each server. Only enable what you actually use.

Pro Tips

1. Use project-level configs for project-specific servers (like database connections) and global configs for universal tools (like GitHub).

1. Don't put secrets directly in mcp.json. Use environment variables or a .env file. Add .cursor/mcp.json to your .gitignore if it contains tokens.

1. Start with 2-3 servers. More servers = more tools for the AI to c slower responses. Add servers as you need them.

1. Check the Cursor docs at cursor.com/docs/mcp for the latest config options. The MCP spec evolves, and Cursor updates frequently.

What's Next

• Browse our best MCP servers for developers to find more tools for your workflow
• Set up MCP in VS Code too: How to Set Up MCP in VS Code
• Read our MCP security guide before connecting production databases
• Compare MCP clients to see how Cursor stacks up against VS Code and Claude Desktop
• Understand the protocol: Model Context Protocol Explained

We track MCP support across 500+ AI tools in our directory. Browse MCP-compatible tools to find the right servers for your stack.