Fix Cursor MCP Server Setup: Configuration and Common Errors

Quick Answer

• What to do: Configure MCP (Model Context Protocol) servers in Cursor by editing the mcp.json file to connect external tools like filesystem, databases, or APIs to your AI assistant.
• First checks: Ensure your Cursor version supports MCP (Agent mode required), verify the server command works in terminal before adding to config, and never hardcode API keys in the JSON file.
• Minimal command: Use npx -y @modelcontextprotocol/server-filesystem /path/to/dir as a quick test server to verify MCP is working.
• Key security rule: Always use ${env:VARIABLE_NAME} syntax for sensitive values and store secrets in environment variables or .env files.
• Version boundary: MCP support is available in Cursor's Agent mode with models that support tool calling (Claude, GPT-4, and Cursor's built-in Agent).

What Problem It Solves

MCP (Model Context Protocol) servers bridge the gap between Cursor's AI assistant and external tools. Without MCP, developers must manually copy-paste file contents, run terminal commands separately, and switch contexts constantly. MCP servers allow the AI to:

• Read and write files directly in your project
• Query databases and APIs
• Execute code and return results
• Access external services through standardized tool calls

This transforms Cursor from a code completion tool into an autonomous coding agent that can interact with your entire development environment.

Installation and Quick Start

Prerequisites

• Cursor with Agent mode enabled
• Node.js installed (for npm-based servers)
• A model that supports tool calling (Cursor's Agent mode uses this by default)

Step 1: Create or Edit mcp.json

Open your Cursor settings and locate the MCP configuration file. The file path is typically:

~/.cursor/mcp.json

Or access it through Cursor Settings → Features → MCP Servers.

Step 2: Add a Minimal Configuration

JSON
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/your/project"
      ],
      "env": {
        "API_KEY": "${env:MY_API_KEY}"
      }
    }
  }
}

Step 3: Test the Server

1. Open Cursor's Output panel (Cmd+Shift+U or Ctrl+Shift+U)
2. Select "MCP Logs" from the dropdown
3. Start a chat in Agent mode and ask the AI to list files in your project
4. Check the logs for connection status and errors

Parameters and Environment Variables

Configuration Parameters

Environment Variable Interpolation

Cursor supports variable interpolation for secure configuration:

• ${env:VARIABLE_NAME} - Reads from your shell environment variables
• ${workspaceFolder} - Expands to the current workspace path
• .env files - Use envFile parameter to load variables from a file

Never hardcode secrets in mcp.json. Always use environment variable references.

Multiple Server Configuration

JSON
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/dir"
      ],
      "env": {
        "API_KEY": "${env:MY_API_KEY}"
      }
    },
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_TOKEN}"
      }
    }
  }
}

Common Errors and Fixes

Error: MCP server connection timeout

Root cause: The server address is unreachable or the port is blocked.

Fix:

1. Verify the server URL or command path is correct
2. For remote servers, test connectivity: curl -v https://api.example.com/mcp
3. Check firewall rules and network access
4. For local servers, confirm the command runs in terminal first

Error: MCP server crashes on startup

Root cause: Missing dependencies, incorrect paths, or permission issues.

Fix:

1. Open Cursor's Output panel (Cmd+Shift+U) and select "MCP Logs"
2. Run the server command manually in terminal to see detailed errors:

   BASH
   npx -y @modelcontextprotocol/server-filesystem /path/to/dir
   

3. Common fixes: install missing packages, fix file paths, grant read/write permissions

Error: Authentication failed: Invalid API key

Root cause: Environment variable not set or incorrect syntax in mcp.json.

Fix:

1. Verify the variable exists: echo $MY_API_KEY
2. Ensure mcp.json uses ${env:MY_API_KEY} syntax (not hardcoded values)
3. If using .env file, confirm envFile path is correct and file uses KEY=VALUE format
4. Restart Cursor after setting environment variables

Error: Tool call failed: File not found

Root cause: Incorrect path in server arguments.

Fix:

1. Use absolute paths or ${workspaceFolder} variable
2. Verify Cursor has read/write permissions for the path
3. For remote servers, check the URL path is correct

Production Notes and Security Checks

Critical Limitations

Security Best Practices

1. Use environment variable interpolation for all secrets:

   JSON
   {
     "env": {
       "DB_PASSWORD": "${env:DB_PASSWORD}"
     }
   }
   

2. Restrict filesystem access to specific directories:

   JSON
   {
     "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path/only"]
   }
   

3. Use read-only API keys when possible for remote services

4. Monitor MCP logs regularly for unexpected activity

5. Keep servers updated by clearing npm cache and reinstalling:

   BASH
   npm cache clean --force
   

FAQ

Q: How do I use multiple MCP servers simultaneously in Cursor?

A: Add multiple entries under mcpServers in your mcp.json file. Each server gets its own key (e.g., "filesystem", "database", "api"). Cursor loads all servers, and you can toggle individual tools on/off in the chat interface. Be aware that multiple servers may compete for resources like file locks, so design your workflow accordingly.

Q: How are images from MCP servers displayed in Cursor?

A: MCP servers can return base64-encoded images. If your AI model supports image analysis (like Claude 3.5 Sonnet), Cursor automatically displays and analyzes the images in chat. Otherwise, images appear as text. Ensure the server response follows the MCP protocol specification for proper rendering.

Q: How do I update an installed MCP server?

A: For npm-managed servers: 1) Remove the server from Cursor settings. 2) Clear npm cache: npm cache clean --force. 3) Re-add the server to get the latest version. For manually configured servers, update the command or args in mcp.json. You may need to restart Cursor for changes to take effect.