MCP Setup in Cursor

You ask the agent to “check if the users table has an email_verified column.” It searches your codebase, finds a migration file from six months ago, and guesses — sometimes correctly, sometimes not. Now imagine the agent could query your database directly, inspect the live schema, and give you a definitive answer. That is what MCP (Model Context Protocol) does. It connects Cursor’s agent to external tools and data sources, turning guesses into facts.

What You’ll Walk Away With

Understanding of what MCP is and how it extends Cursor’s capabilities
A working MCP server configuration using mcp.json
At least one useful MCP server installed and responding to agent queries
Knowledge of the three transport methods (stdio, SSE, Streamable HTTP) and when to use each
Security practices for managing API keys and access credentials

What is MCP?

MCP (Model Context Protocol) is an open protocol that lets AI agents interact with external tools. In Cursor, MCP servers expose tools that the agent can call — querying databases, browsing web pages, interacting with GitHub APIs, reading Figma designs, and more.

Cursor supports three MCP capabilities:

Capability	What It Does
Tools	Functions the agent can execute (query database, create GitHub issue, etc.)
Prompts	Templated workflows the agent can invoke
Resources	Structured data sources the agent can read

How It Works

You configure MCP servers in a JSON file. Cursor starts them automatically and makes their tools available to the agent. When the agent decides a tool is relevant to your prompt, it calls the tool, gets the result, and incorporates it into its response.

Configuration Locations

MCP configuration goes in mcp.json files at one of two locations:

Scope	File Location	Use Case
Project	`.cursor/mcp.json`	Tools specific to this project (commit to git for team sharing)
Global	`~/.cursor/mcp.json`	Tools you want everywhere (personal GitHub token, etc.)

Installing Your First MCP Server

Let us set up a practical MCP server. The GitHub server is a good starting point because it demonstrates the concept immediately and is useful for most projects.

One-Click Installation

Cursor’s MCP directory offers one-click installation for popular servers. Go to Cursor Settings then MCP to browse available servers and click “Add to Cursor” to install them.

Manual Configuration with mcp.json

For more control, create the configuration file directly.

Create the config file
Terminal window
```
mkdir -p .cursor
touch .cursor/mcp.json
```

Add a server configuration

Here is a GitHub MCP server that lets the agent interact with your repositories:

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

Set the environment variable

Add your GitHub token to your shell profile:
Terminal window
```
export GITHUB_TOKEN="ghp_your_token_here"
```
Restart Cursor

MCP servers are loaded at startup. After adding or changing mcp.json, restart Cursor for the changes to take effect.
Verify in the agent panel

Open Agent mode (Cmd+I). You should see the MCP tools listed under “Available Tools” when you hover the context gauge.

Practical MCP Configurations

Database Server (PostgreSQL)

Let the agent query your database schema and run read-only queries:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${env:DATABASE_URL}"
      }
    }
  }
}

With the Postgres MCP server configured, paste this into Agent mode:

Check the current database schema for the users table.
Then create a migration that adds an email_verified boolean column
with a default of false and an index on it.
Use our existing migration patterns.

The agent queries the live schema, sees the current columns, and generates an accurate migration — no guessing required.

Browser MCP Server

Let the agent browse web pages for documentation, checking live sites, or testing:

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Sequential Thinking Server

A reasoning tool that helps the agent work through complex problems step by step:

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}

Combining Multiple Servers

Your mcp.json can include multiple servers. Here is a comprehensive setup:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${env:DATABASE_URL}"
      }
    },
    "browser": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

Remote MCP Servers (SSE and HTTP)

For MCP servers running as remote services (not local CLI tools), use the URL-based configuration:

{
  "mcpServers": {
    "remote-service": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SERVICE_TOKEN}"
      }
    }
  }
}

Remote servers support OAuth authentication. Cursor handles the OAuth flow automatically — you configure the client credentials and Cursor manages token refresh:

{
  "mcpServers": {
    "oauth-service": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "${env:MCP_CLIENT_ID}",
        "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}",
        "scopes": ["read", "write"]
      }
    }
  }
}

Config Interpolation

Cursor supports variable substitution in mcp.json values:

Variable	Resolves To
`${env:NAME}`	Environment variable
`${userHome}`	Your home directory
`${workspaceFolder}`	Project root directory
`${workspaceFolderBasename}`	Project folder name
`${pathSeparator}`	OS path separator

This lets you write portable configurations:

{
  "mcpServers": {
    "custom-tool": {
      "command": "python",
      "args": ["${workspaceFolder}/tools/mcp_server.py"],
      "env": {
        "API_KEY": "${env:CUSTOM_API_KEY}"
      }
    }
  }
}

Tool Approval and Auto-Run

By default, the agent asks permission before calling MCP tools. This is separate from the auto-run setting for terminal commands.

To enable auto-run for MCP tools:

Open Cursor Settings then Agent
Enable auto-run for MCP tools under the security section

Toggling Individual Tools

You can enable or disable specific MCP tools in the agent panel. Click the tool name in the available tools list to toggle it. Disabled tools are not loaded into context and cannot be called.

Security Best Practices

Never hardcode API keys in mcp.json — always use ${env:VARIABLE_NAME}
Use restricted API keys with minimal required permissions
Review server source code for critical integrations before trusting them
Use project-level configs for team-shared servers, global configs for personal tokens
Add .cursor/mcp.json to .gitignore if it contains sensitive environment variable names you do not want in version control (or use ${env:} interpolation and commit the file)

After configuring MCP servers, verify they work:

List all MCP tools currently available to you.
Then use the GitHub tool to list my 5 most recent repositories.

If the agent shows the tools and successfully queries GitHub, your MCP setup is working.

When This Breaks

MCP server fails to start: Check the Cursor output panel (View then Output then select the MCP server from the dropdown) for error messages. Common causes: missing npx, Node.js not in PATH, or invalid JSON in mcp.json.

Tools appear but agent does not use them: The agent uses MCP tools when it determines they are relevant. Mention the tool by name in your prompt: “Use the GitHub MCP tool to check open issues.”

“Permission denied” errors: Your API key or token lacks the required permissions. Check the scopes and permissions for the token you configured.

Server crashes mid-conversation: MCP servers run as separate processes. If one crashes, restart Cursor. If it crashes repeatedly, check memory usage — some servers have high overhead with large datasets.

Environment variables not resolving: Make sure the variable is set in your shell profile (.bashrc, .zshrc), not just the current terminal session. Cursor reads environment variables at startup.

What’s Next

Context Management Master @ symbols, file references, and docs integration -- the context skills that make every prompt more effective.