DEV Community

Serenities AI
Serenities AI

Posted on • Originally published at serenitiesai.com

How to Set Up MCP Servers in Cursor IDE: Complete Guide 2026

#mcp #programming #ai #tutorial

You've heard the buzz about MCP servers in Cursor, but every time you try to set one up, you hit a wall. Maybe the config file isn't being read. Maybe the server starts but Cursor can't see the tools. Or maybe you're just not sure where to begin — stdio, SSE, HTTP… what does any of it mean?

You're not alone. The Model Context Protocol (MCP) is one of the most powerful features in Cursor IDE, letting your AI assistant connect to external tools, databases, APIs, and data sources. But the documentation can feel scattered, and getting your first mcp server cursor setup working requires understanding a few key concepts.

This guide fixes that. By the end, you'll have MCP servers running in Cursor — whether you're a Node.js developer, a Python programmer, or someone deploying remote servers for a team. No guesswork, no frustration, just working configurations.

What You'll Learn

This comprehensive guide covers everything you need to set up and use MCP servers in Cursor IDE:

  • What MCP is and why it matters for AI-assisted development
  • Three transport methods — stdio, SSE, and Streamable HTTP — and when to use each
  • Step-by-step setup for local stdio servers (Node.js and Python examples)
  • Remote server configuration for HTTP and SSE endpoints
  • Configuration locations — project-level vs. global config files
  • Config interpolation — using environment variables and workspace paths
  • OAuth and authentication for secure server connections
  • Using MCP tools in Cursor's chat and agent modes
  • Security best practices to keep your setup safe
  • Troubleshooting tips for common issues

Let's dive in.

Prerequisites

Before you start configuring MCP servers in Cursor, make sure you have these basics in place:

Requirement Details
Cursor IDE Installed and running. MCP support is available on all Cursor plans (Free, Pro, Ultra, and Enterprise).
Node.js (for JS servers) Version 18+ recommended. Needed for npx-based MCP servers.
Python (for Python servers) Version 3.10+ recommended. Needed for Python-based MCP servers.
A terminal You'll need basic command-line comfort for testing servers.
A text editor For editing JSON config files (Cursor itself works great for this).

If you're only setting up remote MCP servers (HTTP/SSE), you don't need Node.js or Python installed locally — just the server URL.

What Is MCP? (Model Context Protocol Explained)

The Model Context Protocol (MCP) is an open standard that enables AI coding assistants like Cursor to connect to external tools and data sources. Think of it as a universal adapter between your AI and the outside world.

Without MCP, your AI assistant is limited to what it can see in your codebase and its training data. With MCP, it can:

  • Query databases directly to understand your schema and data
  • Call APIs — search the web, check deployment status, create tickets
  • Access documentation from external sources in real time
  • Interact with services like GitHub, Jira, Slack, or your own custom tools
  • Read and write files beyond your workspace boundaries

MCP works by defining a standard JSON-RPC protocol between the AI client (Cursor) and external servers. You can write MCP servers in any language that can print to stdout or serve an HTTP endpoint — Python, JavaScript, Go, Rust, and more.

The Five Protocol Capabilities

MCP in Cursor supports five protocol capabilities, all of which are fully supported:

Capability What It Does Cursor Support
Tools Functions for the AI model to execute (e.g., search a database, call an API) ✅
Prompts Templated messages and workflows the server can expose ✅
Resources Structured data sources the AI can query ✅
Roots Server-initiated inquiries into URI or filesystem boundaries ✅
Elicitation Server-initiated requests for additional information from the user ✅

This full protocol support means Cursor's MCP implementation is among the most complete available.

How MCP Works in Cursor: Transport Methods

When setting up an MCP server in Cursor, the first decision you need to make is which transport method to use. Cursor supports three transport types:

Transport Execution Deployment Users Input Auth
stdio Local Cursor manages Single user Shell command Manual
SSE Local/Remote Deploy as server Multiple users URL to SSE endpoint OAuth
Streamable HTTP Local/Remote Deploy as server Multiple users URL to HTTP endpoint OAuth

When to Use Each Transport

stdio (Standard I/O) is the most common choice for individual developers. Cursor launches the server process itself and communicates through stdin/stdout. Use stdio when:

  • You're a solo developer working on your own machine
  • The MCP server needs access to local files or tools
  • You want zero deployment overhead
  • You're using community MCP packages via npx or pip

SSE (Server-Sent Events) is ideal for remote or shared servers. Use SSE when:

  • Multiple team members need the same MCP server
  • The server needs to run persistently
  • You're connecting to a hosted MCP service
  • You need OAuth-based authentication

Streamable HTTP is the newest transport method. Use it when:

  • You're building a new remote MCP server from scratch
  • You want better compatibility with standard HTTP infrastructure
  • You need OAuth authentication
  • Your infrastructure doesn't support SSE well

Step-by-Step: Setting Up stdio MCP Servers

The stdio transport is the fastest way to get an MCP server running in Cursor.

Understanding the Config File

For stdio servers, you'll need these fields:

Field Required Description
type Yes Server connection type — set to "stdio"
command Yes Command to start the server (e.g., npx, node, python, docker)
args No Array of arguments passed to the command
env No Environment variables for the server process
envFile No Path to a .env file (stdio only)

Example 1: Node.js MCP Server via npx

Step 1: Create the config file. In your project root:

mkdir -p .cursor
touch .cursor/mcp.json
Enter fullscreen mode Exit fullscreen mode

Step 2: Add your server configuration:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "your-api-key-here"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 3: Restart Cursor (or reload the window).

Step 4: Verify it's working. Open the Cursor chat (Agent mode) and look for the server's tools listed under "Available Tools."

Example 2: Python MCP Server 

{
  "mcpServers": {
    "my-python-server": {
      "command": "${workspaceFolder}/.venv/bin/python",
      "args": ["${workspaceFolder}/mcp-server.py"],
      "env": {
        "API_KEY": "your-api-key-here"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Running Multiple stdio Servers

You can configure as many MCP servers as you need:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    },
    "database": {
      "command": "python",
      "args": ["db-mcp-server.py"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    },
    "search": {
      "command": "npx",
      "args": ["-y", "mcp-server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-brave-key"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Step-by-Step: Setting Up Remote MCP Servers (HTTP/SSE)

Remote MCP servers are perfect for team environments or hosted services.

Remote Server Configuration 

{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "API_KEY": "your-api-key-here"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Connecting to a Cloud-Hosted MCP Server 

{
  "mcpServers": {
    "team-tools": {
      "url": "https://mcp.yourcompany.com/tools",
      "headers": {
        "Authorization": "Bearer your-team-token"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

SSE vs. Streamable HTTP

  • SSE — Well-established protocol, works great for most deployments
  • Streamable HTTP — Newer standard, better for serverless and modern HTTP infrastructure

If building from scratch, Streamable HTTP is recommended.

Configuration Locations: Project vs. Global

Config Location Path Scope Best For
Project config .cursor/mcp.json Current project only Project-specific tools, shared team config
Global config ~/.cursor/mcp.json All projects Personal tools you want everywhere

When both configs define a server with the same name, the project config takes precedence.

Config Interpolation: Environment Variables and Workspace Paths

Available Interpolation Variables

Variable Resolves To Example
${env:NAME} Environment variable value ${env:GITHUB_TOKEN}
${userHome} Path to home folder ${userHome}/.config/keys.json
${workspaceFolder} Project root directory ${workspaceFolder}/scripts/server.py
${workspaceFolderBasename} Project root folder name Used for dynamic naming
${pathSeparator} or ${/} OS path separator / on Mac/Linux, \ on Windows

Secure API Key Management 

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Then set in your shell profile:

export GITHUB_TOKEN="ghp_your_actual_token_here"
Enter fullscreen mode Exit fullscreen mode

Using envFile for Local Development 

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "envFile": "${workspaceFolder}/.env"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

OAuth and Authentication

For remote MCP servers requiring secure authentication, Cursor supports OAuth flows.

The OAuth callback URL for Cursor is:

cursor://anysphere.cursor-mcp/oauth/callback
Enter fullscreen mode Exit fullscreen mode

Many MCP servers now support one-click installation from the MCP directory, automatically configuring OAuth.

Using MCP Tools in Cursor Chat

Once configured, MCP tools appear under "Available Tools" in the chat interface. The agent automatically uses them when relevant.

Key features:

  • Plan Mode support — MCP tools work in Plan Mode too
  • Toggle tools on/off — Reduce noise by disabling unused tools
  • Tool approval — Default safety feature requiring confirmation before tool execution
  • Auto-run option — Skip approval for trusted servers (use cautiously)
  • Image responses — MCP servers can return base64-encoded images rendered in chat

Security Best Practices

  1. Verify the source — Only install MCP servers from trusted developers
  2. Review permissions — Understand what data and APIs each server can access
  3. Limit API keys — Create dedicated keys with minimal permissions
  4. Audit code — Review source code for critical integrations
  5. Use environment variables — Never hardcode secrets in mcp.json
  6. Keep tool approval enabled — The extra confirmation prevents costly mistakes

Common Troubleshooting Tips

Server Doesn't Appear in Available Tools

  • Verify config file is at .cursor/mcp.json (not .vscode/mcp.json)
  • Check for invalid JSON syntax
  • Restart Cursor or reload the window

Server Starts But Tools Don't Work

  • Check dependencies are installed (Node.js, Python packages)
  • Verify command path (use full path for virtual environments)
  • Run the command manually in terminal to see errors

Environment Variables Not Resolving

  • Ensure variables are set in the right shell context
  • Use ${env:VARIABLE_NAME} syntax (not $VARIABLE_NAME)

Remote Server Connection Fails

  • Verify server is online
  • Check firewall/network connectivity
  • Double-check authentication headers
  • Check for CORS issues

OAuth Flow Fails

  • Verify redirect URI is cursor://anysphere.cursor-mcp/oauth/callback
  • Try disconnecting and reconnecting
  • Check scope configuration

How Serenities AI Integrates with MCP

If you're using Serenities AI as your AI development platform, it supports MCP natively. The same MCP servers you configure in Cursor work with Serenities AI's workflows.

Serenities AI also offers built-in MCP server support — you can expose your Serenities AI workspace as an MCP server that Cursor connects to, creating a powerful two-way bridge between your AI tools.

Frequently Asked Questions

Is MCP available on Cursor's free plan?

Yes. MCP support is available across all Cursor plans, including the free tier.

Can I use MCP servers written in languages other than Node.js and Python?

Absolutely. Any language that can handle JSON-RPC communication works — Go, Rust, Java, Ruby, C#, and more.

What's the difference between project-level and global MCP configuration?

Project-level config (.cursor/mcp.json) only applies to the current project. Global config (~/.cursor/mcp.json) applies to every project. Project config takes precedence if both define the same server name.

Is it safe to commit .cursor/mcp.json to version control?

Yes, as long as you use config interpolation (${env:API_KEY}) instead of hardcoding secrets.

Can MCP servers return images or other non-text data?

Yes. MCP servers can return base64-encoded images rendered directly in Cursor's chat interface.

Conclusion

Setting up MCP servers in Cursor transforms your AI coding assistant from a smart autocomplete tool into a connected, context-aware development partner. With MCP, Cursor can query your databases, check your CI/CD pipelines, search documentation, manage tickets, and interact with virtually any external service.

The MCP ecosystem is growing fast — learn the protocol once, and use it everywhere.

Originally published on Serenities AI

Top comments (0)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.