MCP server not connecting: 6 config mistakes

If an MCP server doesn't show up, shows no tools, or fails right after it starts, the cause is usually one of these six config mistakes. Work through them in order.

1. VS Code uses servers, not mcpServers

Claude Code (.mcp.json), Claude Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json) all put servers under mcpServers. VS Code's workspace file .vscode/mcp.json uses a top-level servers key instead, so an entry copied from another app's config is ignored.

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

Sources: VS Code MCP servers, Cursor MCP, Claude Code MCP.

2. Wrong placeholder syntax for the app

Each app fills in environment variables differently. A placeholder in the wrong syntax is passed through as literal text, and the server then fails to authenticate or can't find a path.

If you put literal values in a config, keep that file out of git. Sources: Claude Code MCP, Cursor MCP, VS Code MCP servers, Connect to local MCP servers (Claude Desktop, which also recommends absolute paths).

3. Node.js is too old

Run node --version in the same shell or environment the app uses. Node 20+ covers most servers, but some need newer versions:

• DBHub (@bytebase/dbhub, used for Postgres and SQLite) needs Node 22.5+. It uses node:sqlite and declares engines >=22.5.0.
• The current filesystem, memory and sequential-thinking servers (@modelcontextprotocol/server-* 2.0.0) need Node 24+, according to their npm metadata.

Check any package yourself with npm view <package> engines. Source: DBHub on GitHub.

4. Windows: npx won't start

On Windows, npx is a .cmd shim, and some apps can't launch it directly. A common community fix (not documented officially) is to wrap it:

"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"]

5. The package is deprecated or archived

Older tutorials still point at servers that are no longer maintained:

• @modelcontextprotocol/server-slack: deprecated on npm. Use Slack's official hosted MCP server instead (OAuth; your workspace admin must approve it).
• @modelcontextprotocol/server-puppeteer: deprecated on npm. Use Microsoft's @playwright/mcp.
• mcp-server-sqlite: archived. Use DBHub (--transport stdio --dsn sqlite:///absolute/path.db).

The old code lives in modelcontextprotocol/servers-archived.

6. uv / uvx isn't installed

The Python reference servers (fetch, git and time) are usually launched with uvx, for example "command": "uvx", "args": ["mcp-server-fetch"]. If uv isn't installed, or isn't on the PATH the app sees, the server never starts. Install uv, or point command at the absolute path from which uvx (or where uvx on Windows).

Still stuck? Check the logs

A server must not print anything except MCP messages to stdout. Logs belong on stderr (MCP transports spec). Claude Desktop writes mcp*.log files to ~/Library/Logs/Claude on macOS and %APPDATA%\Claude\logs on Windows. In Claude Code, a slow first npx download can hit the startup timeout, which you can raise with MCP_TIMEOUT.

Independent guide, not affiliated with or endorsed by Anthropic, Cursor, Microsoft, GitHub, Slack, Bytebase, Astral, or any other vendor mentioned.