Configuring MCP servers

What MCP servers are

Model Context Protocol (MCP) servers are external processes that give AI coding agents access to tools and data sources beyond the IDE. A GitHub MCP server lets agents read your repositories. A PostgreSQL MCP server lets agents query your database. A Playwright MCP server lets agents control a browser.

MCP is an open standard by Anthropic, now supported by most major AI coding tools. Servers run as local processes (stdio) or remote HTTP endpoints, communicating with agents through a standardized protocol.

Server types

Local stdio servers

Run on your machine as child processes. The AI tool launches them automatically when needed.

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

Pros: No network exposure, works offline, full local data access Cons: Requires Node.js/Python on the machine, per-machine setup

Remote HTTP servers

Hosted services accessible via URL. Common for SaaS integrations.

{
  "mcpServers": {
    "remote-service": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

Pros: No local dependencies, centralized management Cons: Requires network access, potential latency

Setup by tool

Cursor

Configuration file: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

After editing the config, restart Cursor completely. MCP servers load at startup.

You can also add servers through the UI: Settings > Tools & MCP > Add new MCP server.

Claude Code / Claude Desktop

Configuration file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
      }
    },
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_API_KEY": "ntn_your_key"
      }
    }
  }
}

Restart Claude Desktop after configuration changes.

VS Code / GitHub Copilot

Use the CLI command to add servers:

code --add-mcp '{"name":"github","command":"npx","args":["-y","@modelcontextprotocol/server-github"],"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"ghp_your_token"}}'

Or edit .vscode/mcp.json in your project.

OpenAI Codex

Codex can act as both an MCP client and server. To expose Codex as an MCP server for other tools:

codex mcp-server

For using MCP servers within Codex, configure through AGENTS.md skill references or the Agents SDK integration.

Common server configurations

Development starter pack

A typical development setup with GitHub, docs, and browser testing:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Full-stack development

Add database and project management context:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost:5432/devdb"]
    },
    "linear": {
      "command": "npx",
      "args": ["-y", "@linear/linear-mcp-server"],
      "env": { "LINEAR_API_KEY": "lin_api_..." }
    }
  }
}

Authentication patterns

Server	Auth method	Token format
GitHub	PAT	ghp_...
Notion	Integration token	ntn_...
Linear	API key	lin_api_...
Slack	Bot token	xoxb-...
PostgreSQL	Connection string	postgresql://user:pass@host:port/db
Playwright	None	Local process
Filesystem	None	Local process
Context7	None	Public docs access

Security best practices

• Environment variables over hardcoded values: Use env vars in config files and set them in your shell profile
• Least privilege tokens: Grant only the permissions each server needs
• Project-scoped configs: Prefer .cursor/mcp.json per-project over global config for team-shared setups
• Separate read/write tokens: Use read-only tokens when agents only need to fetch context
• Never commit secrets: Add config files with tokens to .gitignore, or use env var references

Troubleshooting

Problem	Solution
Server not loading	Restart the IDE completely (not just reload window)
"Command not found"	Ensure Node.js 18+ is installed and npx is in PATH
Auth failures	Verify token permissions and expiration dates
Timeout errors	Check network access for remote servers; verify database connectivity for local servers
Server crashes on start	Run the server command manually in terminal to see error output

Finding MCP servers

• Official directory: modelcontextprotocol.io
• npm registry: Search for @modelcontextprotocol/server-* packages
• Community list: awesome-mcp-servers (3,600+ stars)
• MCP Registry: registry.modelcontextprotocol.io