Connect an MCP Server to Clients

All file-based clients share the mcpServers shape. What differs is the file location, the variable syntax, and a few Windows quirks. Ready-made configs are in templates/client-configs/.

Paths: use absolute paths to your server, written with forward slashes (C:/Projects/notes-server/build/index.js). In JSON, backslashes must be doubled (C:\\Projects\\...), so forward slashes avoid mistakes.

Cursor

Files: .cursor/mcp.json (project, commit it for the team) or ~/.cursor/mcp.json (global). If the same server name appears in both, the project file wins.

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["C:/Projects/notes-server/build/index.js"],
      "env": { "NOTES_FILE": "${userHome}/.notes-mcp.json" }
    },
    "internal-api": {
      "command": "npx",
      "args": ["-y", "@acme/internal-mcp"],
      "envFile": "${workspaceFolder}/.env"
    },
    "remote-example": {
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:EXAMPLE_TOKEN}" }
    }
  }
}

• Variables: ${env:NAME}, ${userHome}, ${workspaceFolder}, ${workspaceFolderBasename}, ${pathSeparator}.
• envFile works for stdio servers only.
• OAuth: remote servers that support OAuth prompt you to sign in. For static OAuth, add an auth object with CLIENT_ID, CLIENT_SECRET, and scopes.
• Manage: Customize → MCPs, where you can toggle servers and see their tools. You can toggle individual tools from the chat tools list.
• Logs: Output panel (Ctrl+Shift+U) → “MCP Logs”.
• Verify: The server shows a green dot and lists its tools. Asking a question that needs a tool triggers an approval prompt, or runs it directly if the tool is allowlisted.

Claude Code

Add from the CLI, the recommended way:

# local stdio server (scope: local = just you, this project — the default)
claude mcp add notes -- node C:/Projects/notes-server/build/index.js

# with env vars
claude mcp add notes -e NOTES_FILE=C:/Users/me/.notes-mcp.json -- node C:/Projects/notes-server/build/index.js

# remote HTTP server
claude mcp add --transport http example https://mcp.example.com/mcp

# share with the team via .mcp.json in the repo root
claude mcp add --scope project notes -- node ./tools/notes-server/build/index.js

# available in all your projects
claude mcp add --scope user notes -- node C:/Projects/notes-server/build/index.js

claude mcp list          # check status
claude mcp get notes     # details
claude mcp remove notes

.mcp.json (project scope, committed):

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["./tools/notes-server/build/index.js"],
      "env": { "NOTES_FILE": "${NOTES_FILE:-./notes.json}" }
    }
  }
}

• Variables in .mcp.json: ${VAR} and ${VAR:-default}.
• Windows (native, not WSL): npx-based servers need a wrapper: claude mcp add my-server -- cmd /c npx -y some-package.
• Inside a session: /mcp shows status and handles OAuth sign-in.
• Debug: claude --debug, or claude --mcp-debug on older versions.

Claude Desktop

File: open Settings → Developer → Edit Config.

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

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["C:/Projects/notes-server/build/index.js"],
      "env": { "NOTES_FILE": "C:/Users/me/.notes-mcp.json" }
    }
  }
}

• Fully quit and restart Claude Desktop after editing (on Windows, quit it from the system tray).
• There’s no variable interpolation, so values are literal.
• One-click install: a .mcpb bundle can be opened directly (see Security & production).
• Logs: %APPDATA%\Claude\logs\mcp*.log (Windows), ~/Library/Logs/Claude/mcp*.log (macOS).

Claude.ai (web) and Claude mobile

• Remote servers only (Streamable HTTP or SSE over HTTPS). Local stdio servers can’t be used.
• Settings → Connectors → Add custom connector → enter the server URL. OAuth is supported.
• Org admins may need to enable custom connectors.

SDK agents

• Claude Agent SDK: pass mcpServers: { notes: { command, args, env } } in options, or load .mcp.json via settingSources: ["project"].
• Cursor SDK: pass MCP servers inline on Agent.create / agent.send, or opt in to .cursor/mcp.json via local.settingSources. Inline servers aren’t persisted when you resume an agent, so pass them again.

Common connection failures

Symptom	Cause	Fix
Red dot / “failed to start”	Wrong path, or node / uv not on PATH for GUI apps	Use absolute paths, including the absolute path to node.exe if needed
Connects then drops immediately	Something writes to stdout	Log to stderr only
“Connection closed” on Windows with npx	The Windows shell wrapper is missing	Claude Code: cmd /c npx …
Tools don’t appear	Server not restarted after a change; build not re-run	Rebuild; toggle the server off and on; restart the host
Env var not set	Wrong interpolation syntax for that client	Check the syntax per client (above)
OAuth loop	Redirect URL not registered	Register the client’s callback URL with the provider
Too many tools / wrong tool picked	Several servers with overlapping tools	Disable unused servers and tools