How to Link MCP to Claude Desktop, Cursor, and Claude Code

To connect external data sources and local tools to an AI coding agent, configure a Model Context Protocol (MCP) server in your client settings. Claude Desktop, Cursor, and Claude Code each read server definitions through JSON files or direct CLI commands, running local tools over standard input and output (stdio) or connecting to remote endpoints over HTTP. Once linked, the agent discovers and invokes tools on demand without loading full schemas into every context window.

Before you start

• Node.js version 18 or higher installed with npx available.
• Claude Desktop, Cursor, or Claude Code installed.
• Absolute paths to any local directories or resources you plan to expose.

How it works

flowchart LR
  A[Client starts] --> B[Read MCP config file]
  B --> C[Spawn server subprocess via stdio]
  C --> D[Discover available tools]
  D --> E[Agent invokes tool on demand]

Step 1: Configure Claude Desktop

Open your operating system configuration file. On macOS, open ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, open %APPDATA%\Claude\claude_desktop_config.json.

Define your server under the mcpServers object using absolute system paths:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/Users/username/Downloads"
      ]
    }
  }
}

Step 2: Configure Cursor

Create or edit the MCP configuration file in Cursor. Use ~/.cursor/mcp.json for global access across all projects, or .cursor/mcp.json in your workspace root for repository-specific tools.

Add your server definition with required arguments and environment variables:

{
  "mcpServers": {
    "postgres-db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "PG_DB_MAP": "{\"my_db\":\"postgresql://localhost:5432/my_db\"}"
      }
    }
  }
}

Step 3: Register servers in Claude Code

Add servers directly from your terminal using the claude mcp add command. For local stdio processes, place -- between client options and the executable command:

claude mcp add local-tools -- npx -y @example/mcp-server

For remote servers hosted over HTTP, specify the transport flag:

claude mcp add --transport http remote-service https://example.com/mcp

Claude Code writes local configurations to .mcp.json in your project root and user configurations to ~/.claude.json.

Step 4: Configure Windsurf

Open the Windsurf configuration file on your machine. On macOS and Linux, edit ~/.codeium/windsurf/mcp_config.json. On Windows, edit %USERPROFILE%\.codeium\windsurf\mcp_config.json.

Define your server inside the mcpServers object:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"],
      "env": {}
    }
  }
}

In Windsurf, open the Cascade chat panel, click the hammer icon, select Configure, and choose View raw config to open this file, then click Refresh to reload your tools.

Step 5: Verify the connection

Confirm that the client recognizes the registered tools. In Claude Code, run the listing command:

claude mcp list

In Claude Desktop, look for the hammer icon in the chat interface. In Cursor, open Settings and verify that the server status indicator is active in the Tools and MCP section.

Common mistakes

• Using relative directory paths. MCP hosts execute servers in isolated environments. Arguments containing relative paths like ./data or ~/Desktop will fail. Always use absolute paths.
• PATH resolution failures in desktop applications. GUI apps like Claude Desktop and Cursor do not inherit shell profile paths from managers like nvm. Replace "command": "npx" with the absolute binary path (such as "/usr/local/bin/npx") if the client reports ENOENT or command not found.
• Failing to quit the host application. Claude Desktop loads server definitions only at startup. Closing the active window does not reload configuration. Quit the application completely from the system dock or menu bar, then relaunch.
• JSON syntax formatting errors. Missing commas or unescaped backslashes on Windows will invalidate the configuration file without explicit error banners.
• Polluting stdout in stdio servers. Local servers communicate using JSON-RPC over stdout. Emitting raw console logs or package update notices breaks JSON parsing. Direct diagnostic logging to stderr and pass -y to package runner commands.

Frequently asked questions

When should you use stdio versus HTTP transport?

Use stdio for local subprocesses like filesystems, local databases, or custom command scripts running on your machine. Use HTTP for remote services and hosted APIs where you want to access centralized systems without running local runtimes.

Should an MCP configuration live in user scope or project scope?

Use user-scoped configurations like ~/.cursor/mcp.json or ~/.claude.json for personal tools you want available across all work. Use project-scoped files like .mcp.json committed to version control when standardizing database tools or APIs for a team.

Do MCP servers consume context window space before use?

No. MCP servers expose compact tool signatures to the model. The full response data enters the context window only when the agent explicitly executes a tool call, keeping baseline prompt overhead low.

Related

• Large Context Window Prompting: 2M Token Guide details how selective tool retrieval keeps long sessions within context budgets.
• Why AI Coding Agent Tools Prefer Grep Over LSP Servers analyzes latency and accuracy tradeoffs when designing agent tooling.
• How to Package and Share AI Agent Skills with Your Team explains how to commit project-level configurations into shared repositories.
• Skills, Commands, Subagents or Hooks: Which to Use compares MCP tools against native Claude Code extensibility primitives.
• Review the Claude Code MCP Quickstart for additional CLI syntax and authentication commands.