Fix mcpServers versus servers configuration errors

Use the container key required by the client

An MCP configuration is not portable just because every client uses JSON. Claude Code, Claude Desktop, and Cursor examples place named entries under `mcpServers`; current VS Code configuration places them under `servers`. If a guide tells you to replace one key with the other globally, stop and identify the client, configuration file, scope, and transport first. The server definition may be valid while sitting under a container that the host never reads.

Fix the smallest boundary. Open the configuration through the client's own command or settings UI when possible, confirm the file path it opened, and compare the complete outer object with that client's current documentation. Do not paste a bare server entry where a full document is expected, and do not wrap a full `mcpServers` document inside VS Code's `servers` object. Preserve secrets outside shared files while testing the structural change.

Claude family and Cursor examples

`mcpServers`Used by the documented Claude Code `.mcp.json` format, Claude Desktop local-server configuration, and Cursor `mcp.json` examples.

VS Code example

`servers`Used at the top level of VS Code's current `mcp.json` schema.

Dated client compatibility ledger

This ledger was checked on 2026-08-09 against current first-party documentation. For Claude Code, a project-scoped server belongs in `.mcp.json` at the project root; user and local scopes live in `~/.claude.json`. Those JSON forms use `mcpServers`. A local entry uses `type: "stdio"` with `command` and optional `args` or `env`; a remote entry uses `type: "http"` with `url` and optional `headers`.

For VS Code, workspace configuration is `.vscode/mcp.json`, while the command `MCP: Open User Configuration` opens the profile-specific user file. Its top-level container is `servers`. The current reference documents `stdio` entries with `command`, optional `args`, `cwd`, `env`, and `envFile`; HTTP or SSE entries use `type`, `url`, and optional `headers` or `oauth`. For Claude Desktop's documented local-server flow, Developer > Edit Config opens `claude_desktop_config.json`, and named local processes sit under `mcpServers` with `command` and `args`.

For Cursor, current documentation configures custom servers in `mcp.json` under `mcpServers`. Project-scoped tools use `.cursor/mcp.json`; global tools use `~/.cursor/mcp.json`. Documented stdio examples use `command` with optional `args` and `env`; remote examples use `url` with optional `headers`.

Claude Code

project `.mcp.json` or scoped `~/.claude.json`Top-level server map: `mcpServers`; explicit transport type is documented.

VS Code

workspace `.vscode/mcp.json` or profile user configurationTop-level server map: `servers`; use the MCP commands to open the effective file.

Claude Desktop local server

`claude_desktop_config.json`Top-level server map: `mcpServers`; the documented local example launches a command with arguments.

Cursor

project `.cursor/mcp.json` or global `~/.cursor/mcp.json`Top-level server map: `mcpServers` in current Cursor MCP examples.

Compare the whole document, not one copied property

For a Claude Code project, the structural shape is a root object containing `mcpServers`, followed by a unique server name and its transport fields. Cursor uses the same outer key in its documented `mcp.json` examples, but the file path is under `.cursor/` rather than the Claude Code project root. For a VS Code workspace, the parallel shape is a root object containing `servers`. The nested server name can stay the same when translating, but the destination container and accepted transport fields come from the destination client's schema.

Do not assume that changing `mcpServers` to `servers` is the complete migration. A remote definition copied from Claude Code may contain a transport spelling or header form that needs checking against VS Code's reference. A local definition copied in the other direction may rely on VS Code variables, `envFile`, a workspace-relative `cwd`, or input placeholders that another host does not document. Rebuild the small entry from the destination reference, then transfer only the command, arguments, URL, and non-secret names that still apply.

Wrong outer key

No server appearsMove the named entry under the destination client's documented container; do not change the server itself yet.

Right key, wrong entry shape

Schema or startup errorCompare required transport fields, value types, and client-specific variables before testing the endpoint.

Trace file, scope, schema, and transport in that order

First prove that you edited the active file. In Claude Code, distinguish project, local, and user scope; a project `.mcp.json` is not interchangeable with an invented path under `~/.claude/`. In VS Code, use the MCP commands to open workspace, remote-user, or profile-user configuration instead of guessing where a profile stores `mcp.json`. In Claude Desktop, use Developer > Edit Config so the application selects its platform-specific file. In Cursor, confirm whether you intended the project `.cursor/mcp.json` or the global `~/.cursor/mcp.json`.

Second validate the outer JSON and container key. Third validate the named entry against the selected transport: a local stdio process needs an executable context, while a remote HTTP connection needs a URL and the client's documented HTTP type and authentication fields. Only after those checks should you investigate network access, authorization, or the MCP server. This order prevents an unrecognized `servers` or `mcpServers` object from being misdiagnosed as a token or endpoint failure.

Finally reload through the host's documented lifecycle. Claude Code's quickstart says to start a new session after saving project configuration. The Claude Desktop local-server guide requires a complete quit and restart. VS Code can restart a configured server from its MCP management surfaces and exposes server output for diagnosis.

Read the symptom as a configuration boundary

If the client shows no server at all, prioritize file location, scope, JSON parsing, and the outer key. If the server appears but fails before connecting, the container was probably recognized; inspect required fields, executable lookup, arguments, working directory, and environment names for stdio. If a remote server appears but returns an HTTP or authorization error, keep the recognized schema and move to URL, headers, OAuth, proxy, and server-response diagnostics.

A July 2026 merged pull request in a third-party project illustrates why copied snippets need this separation. Its maintainers reported that one setup guide emitted the same remote-style snippet for Claude Desktop and Claude Code, then changed the guide to client-specific forms. Treat that report as an implementation anecdote, not a universal compatibility rule: the reliable evidence is still each client's current documentation and the error produced by the client being configured.

Record the before-and-after observation. A successful schema correction should make the named server visible or move the failure to a more specific startup, transport, or authentication message. If nothing changes, return to the effective file and scope rather than rotating a credential. Never publish a full configuration containing API keys, bearer headers, cookies, or private endpoint parameters.

Choose the next guide from the first recognized boundary

Return to the MCP troubleshooting directory when the host still does not recognize any configured server after the file, scope, and outer key are verified. Use the stdio startup guide when a correctly registered local entry launches and immediately exits. Use the insufficient-credits guide only after configuration, connection, authentication, and tool discovery succeed and a generation request returns the documented credit error.

Keep this page limited to client schema mismatch

This page owns the mismatch between `mcpServers` and `servers`, the effective configuration file and scope, and the transport fields a named client documents. It does not claim one JSON shape works in every MCP host, and it does not own executable crashes, OAuth failures, missing tools after discovery, rate limits, credits, or generation failures.

The last30days run used the tracked plan and completed with degraded coverage. It returned 118 review-queue items across Digg, GitHub, grounding, Hacker News, Instagram, Reddit, TikTok, and YouTube; only one item directly described a copied client-schema error. Reddit was partial, the jobs lane was unreachable, and X was not configured. The dated ledger therefore relies on current Claude Code, VS Code, Model Context Protocol, and Cursor documentation. Recheck it under the monthly freshness cadence, and preserve an explicit gap for clients whose current first-party schema could not be retrieved.