SOP-012: MCP Server Setup

Document Control

Field	Value
SOP ID	SOP-012
Version	1.0
Status	Active
Last Updated	2024-12

Purpose

This SOP covers setting up Model Context Protocol (MCP) servers to connect Cursor to external tools and data sources.

Scope

• One-click MCP installation
• Manual configuration with mcp.json
• Transport types (STDIO, SSE, HTTP)
• Security considerations

Prerequisites

• Cursor installed and configured
• For CLI servers: Node.js or Python installed

---

Procedure

MCP Overview

Architecture: Cursor Agent ↔ MCP Protocol ↔ MCP Server ↔ External Services (Database, APIs)

Transport Types:

Type	Description
STDIO	Local command-line servers
SSE	Server-sent events (local/remote)
HTTP	Streamable HTTP (local/remote)

Step 1: One-Click Installation

Browse available servers at cursor.com/docs/context/mcp/directory

Popular MCP Servers:

Server	Purpose
Notion	Notes, docs, project management
Figma	Design files and components
Linear	Issue tracking
Playwright	Browser automation
Context7	Documentation lookup

Install Process:

1. Visit MCP Directory
2. Click "Add to Cursor" on desired server
3. Authenticate if required (OAuth)
4. Server appears in chat

Step 2: Manual Configuration (mcp.json)

For servers not in directory or custom setups.

Configuration Locations:

Scope	Path
Project	.cursor/mcp.json
Global	~/.cursor/mcp.json

Step 3: Configure STDIO Server

For local command-line servers:

Node.js Example:

{
  "mcpServers": {
    "my-database": {
      "command": "npx",
      "args": ["-y", "@my-org/db-mcp-server"],
      "env": {
        "DATABASE_URL": "${env:DATABASE_URL}"
      }
    }
  }
}

Python Example:

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

Configuration Fields:

Field	Required	Description
type	No	"stdio" (default for command-based)
command	Yes	Executable to run
args	No	Command arguments
env	No	Environment variables
envFile	No	Path to .env file

Step 4: Configure Remote Server

For HTTP/SSE endpoints:

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

Step 5: Use Config Variables

Supported interpolation:

Variable	Description
${env:NAME}	Environment variable
${userHome}	Home directory
${workspaceFolder}	Project root
${workspaceFolderBasename}	Project folder name
${pathSeparator} or ${/}	OS path separator

Example with Variables:

{
  "mcpServers": {
    "project-tools": {
      "command": "node",
      "args": ["${workspaceFolder}/scripts/mcp-server.js"],
      "env": {
        "HOME": "${userHome}",
        "PROJECT": "${workspaceFolderBasename}"
      }
    }
  }
}

---

Using MCP in Chat

Toggle Servers

1. Start a chat session
2. Click "Available Tools" in chat
3. Toggle servers on/off by clicking their names

Tool Approval

By default, Agent asks before using MCP tools:

Agent wants to use: my-database.query

Arguments: { "sql": "SELECT * FROM users" }

Options: [Run] [Skip]

Auto-Run MCP Tools

Add to allowlist in Settings → Cursor Settings → Agents → MCP Allowlist

---

Protocol Capabilities

Feature	Support	Description
Tools	✅	Functions AI can call
Prompts	✅	Templates for workflows
Resources	✅	Structured data sources
Roots	✅	Filesystem boundaries
Elicitation	✅	Server requests for info

---

Security Best Practices

• Verify source - Install from trusted developers only
• Review permissions - Check what data/APIs server accesses
• Limit API keys - Use restricted keys with minimal permissions
• Audit code - Review source for critical integrations
• Use environment variables - Never hardcode secrets
• Monitor usage - Check what tools are being called

---

Debugging MCP Issues

View Server Status:

1. Open Command Palette
2. Search "MCP: Show Servers"
3. View status and logs

Common Issues:

Issue	Solution
Server not starting	Check command path, dependencies
Authentication failed	Verify API keys, re-authenticate
Tool not appearing	Check mcp.json syntax, restart
Timeout errors	Check network, increase timeout

---

Verification Checklist

• [ ] mcp.json created in correct location
• [ ] Server appears in Available Tools
• [ ] Can toggle server on/off
• [ ] Tool calls work as expected
• [ ] Environment variables resolved correctly
• [ ] Authentication works (if required)

Troubleshooting

Issue	Solution
Server won't connect	Check mcp.json syntax
Command not found	Verify command is in PATH
Env vars not working	Use correct ${env:VAR} syntax
OAuth failing	Clear cache, re-authenticate
Server crashes	Check logs, review server code

See Also

• MCP Directory
• Building an MCP Server
• SOP-015: Team & Enterprise