Chapter 12: Configuration

Plugging It All In

You’ve built an MCP server. Congratulations. Now you need to tell your AI application about it. This chapter covers how to configure MCP servers in every major host application.

The good news: the configuration format is similar across applications. The bad news: “similar” is not “identical,” and the devil lives in the details.

Claude Desktop

Claude Desktop was the first MCP host and remains the reference implementation.

Configuration File Location

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

Format

{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "KEY": "value"
      }
    }
  }
}

Examples

Filesystem server:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"],
      "env": {}
    }
  }
}

Python server with uvx:

{
  "mcpServers": {
    "weather": {
      "command": "uvx",
      "args": ["weather-mcp-server"],
      "env": {
        "WEATHER_API_KEY": "your-key-here"
      }
    }
  }
}

Multiple servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    },
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "/Users/me/data/mydb.sqlite"]
    }
  }
}

Important Notes

Claude Desktop currently only supports stdio transport
Restart Claude Desktop after changing the config file
Check the logs at ~/Library/Logs/Claude/mcp*.log (macOS) for debugging
The server name (the key) can be anything—it’s for your reference

Claude Code (CLI)

Claude Code, Anthropic’s CLI coding agent, has comprehensive MCP support with multiple scopes and transport types.

Configuration Scopes

Claude Code supports three scopes:

Scope	Flag	Storage	Visibility
local (default)	`--scope local`	`~/.claude.json` under project path	Only you, current project
project	`--scope project`	`.mcp.json` at project root (committed to VCS)	Everyone on the team
user	`--scope user`	`~/.claude.json`	You, across all projects

Project-Level Configuration (`.mcp.json`)

This file gets committed to version control—great for team-shared servers:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Note the ${VAR} and ${VAR:-default} syntax—Claude Code supports environment variable expansion in command, args, env, url, and headers.

Using the CLI

# Add an HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Add with auth headers
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# Add a local stdio server
claude mcp add --transport stdio --env API_KEY=sk-123 my-server \
  -- npx -y my-mcp-server

# Add from raw JSON
claude mcp add-json weather '{"type":"http","url":"https://weather.example.com/mcp"}'

# Import servers from Claude Desktop config
claude mcp add-from-claude-desktop

# List, inspect, remove
claude mcp list
claude mcp get my-server
claude mcp remove my-server

Inside a Claude Code session, use /mcp to check server status and handle OAuth authentication.

Remote Server Support

{
  "mcpServers": {
    "remote-api": {
      "type": "http",
      "url": "https://my-server.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

VS Code (GitHub Copilot)

VS Code added MCP support for GitHub Copilot’s agent mode.

Configuration File

MCP servers are configured in .vscode/mcp.json at the workspace level, or in user settings for global configuration.

Format

{
  "inputs": [
    {
      "type": "promptString",
      "id": "api-key",
      "description": "API Key",
      "password": true
    }
  ],
  "servers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"],
      "env": {
        "API_KEY": "${input:api-key}"
      }
    }
  }
}

Key Differences from Claude Desktop

Uses servers instead of mcpServers
Supports an inputs array for securely handling secrets
Supports ${input:id} variable substitution for API keys
Supports ${workspaceFolder} and other VS Code variables
Supports stdio, HTTP, and SSE transports

Transport Types

stdio:

{
  "servers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

HTTP (Streamable HTTP):

{
  "servers": {
    "remote": {
      "type": "http",
      "url": "https://api.example.com/mcp"
    }
  }
}

Adding Servers

Command Palette: Ctrl+Shift+P → “MCP: Add Server”
Extensions View: Search @mcp to browse available servers
Manual: Edit .vscode/mcp.json directly
Command Line: code --add-mcp '{...}'

Server Management

Start/stop servers via the Extensions view
View logs with “MCP: List Servers” command
Reset cached tools with “MCP: Reset Cached Tools”

Cursor

Cursor uses a configuration format similar to Claude Desktop.

Configuration File Locations

Global: ~/.cursor/mcp.json
Project: .cursor/mcp.json in the project root

Format

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"]
    }
  }
}

HTTP Server Configuration

{
  "mcpServers": {
    "remote-server": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "API_KEY": "your-key"
      }
    }
  }
}

Adding Servers via UI

Navigate to File → Preferences → Cursor Settings → MCP to manage servers through the settings UI.

Windsurf

Windsurf (by Codeium) also supports MCP.

Format

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"],
      "env": {
        "KEY": "value"
      }
    }
  }
}

The format follows the same pattern as Claude Desktop.

Configuration Tips

1. Use npx with `-y`

For Node.js servers, always use npx -y:

{
  "command": "npx",
  "args": ["-y", "package-name"]
}

The -y flag auto-confirms installation, preventing the server from hanging waiting for user input.

2. Use uvx for Python

For Python servers:

{
  "command": "uvx",
  "args": ["package-name"]
}

uvx handles creating an isolated environment and installing dependencies.

3. Absolute Paths for Local Scripts

When running a local script, use absolute paths:

{
  "command": "node",
  "args": ["/absolute/path/to/server.js"]
}

Relative paths may not resolve correctly depending on the host’s working directory.

4. Environment Variables for Secrets

Never put secrets in the command args (they may appear in process listings). Use env:

{
  "command": "npx",
  "args": ["-y", "my-server"],
  "env": {
    "API_KEY": "sk-secret-key"
  }
}

Better yet, use VS Code’s inputs feature or reference environment variables from a .env file.

5. Test Before Configuring

Before adding a server to your config, test it manually:

# For Node.js servers
npx -y my-mcp-server

# For Python servers
uvx my-mcp-server

# Then send a test message
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | npx -y my-mcp-server

6. Check the Logs

When things go wrong:

Claude Desktop: ~/Library/Logs/Claude/mcp*.log
Claude Code: Use --verbose flag or check ~/.claude/logs/
VS Code: “MCP: List Servers” → “Show Logs”
Cursor: Check the output panel for MCP-related messages

The Emerging Standard

While configuration formats differ slightly between hosts, the trend is toward convergence. The core pattern is consistent:

{
  "mcpServers": {
    "name": {
      "command": "executable",
      "args": ["arguments"],
      "env": { "KEY": "VALUE" }
    }
  }
}

For HTTP servers:

{
  "mcpServers": {
    "name": {
      "url": "https://server.example.com/mcp",
      "headers": { "Authorization": "Bearer token" }
    }
  }
}

This consistency means a server that works in Claude Desktop will almost always work in Cursor, VS Code, and other hosts with minimal configuration changes.

Summary

Configuring MCP servers is straightforward: point your host at the server executable (for stdio) or URL (for HTTP), provide any necessary environment variables, and restart.

The main hosts—Claude Desktop, Claude Code, VS Code, Cursor, and Windsurf—all support the core configuration pattern with minor variations. Test your servers manually first, use absolute paths, keep secrets in environment variables, and check the logs when things go wrong.

Next: keeping those connections secure.

Keyboard shortcuts

The Model Context Protocol Book