What Is an MCP Config? A Complete Structure Guide

An MCP config is a JSON file that tells an AI client which Model Context Protocol (MCP) servers to start and how to reach them. Most configs wrap server definitions in a top-level mcpServers object; the exceptions are VS Code, which uses servers, and Zed, which usescontext_servers.

The mcpServers wrapper

The outer object is usually mcpServers. Inside it, each key is a server name you choose, and the value is a server object. Server names must be unique within the file.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "weather": {
      "url": "https://weather.example.com/mcp"
    }
  }
}

The weather entry is a remote server. Its exact shape depends on the client: Cursor, Claude Code, and Zed read url as shown; VS Code addstype:"http"; Cline uses type:"streamableHttp"; Windsurf calls the field serverUrl; Claude Desktop does not read remote entries from hand-written JSON at all. See theclient compatibility matrix.

Server object fields

A server object contains the connection details. Either command or url is required; everything else depends on the transport and client.

command: The executable to launch for stdio servers, such as npx or python3.
args: An array of arguments passed to command. Include -y for npx so it does not wait for confirmation.
env: An object of environment variable key-value pairs, both strings. Used for tokens and settings.
url: The remote endpoint for Streamable HTTP or SSE servers. Must include http:// or https://.
type (client-specific): Some clients declare the remote transport with a type field: http/sse/stdio in VS Code, streamableHttp in Cline. Clients without a type field (Claude Desktop, Cursor, Windsurf, Zed) infer the transport from the fields present. No verified client reads a server-level transport field.
enabled / disabled: Optional booleans used by some clients, such as Cline, to turn a server on or off without deleting it.
autoApprove: A Cline-specific array of operation names that can run without asking for permission each time.
headers: Optional object of HTTP headers sent with remote transport requests, typically for authentication.

The env object

The env object holds environment variables as string key-value pairs. Values are stored in plaintext, so keep the config file out of git and screenshots. If a server needs a token, put it here, not in args.

"env": {
  "GITHUB_TOKEN": "<your-github-token>",
  "OPENWEATHER_API_KEY": "<your-openweather-key>"
}

Transports in a config

stdio servers use command and args; remote servers use a URL field (url, or serverUrl in Windsurf) plus a client-specific type token where the client defines one. See the full transport comparison for details.

Valid vs invalid example

A single trailing comma after the last array item makes the whole file invalid JSON. The fixed version removes it.

Invalid

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

Fixed

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

Client-specific wrappers

Most clients read mcpServers (Claude Desktop, Claude Code, Cursor, Windsurf, Cline). VS Code reads a top-level servers object in .vscode/mcp.json, and Zed reads context_servers inside its settings.json. Thecompatibility matrix compares all seven clients.

Frequently asked questions

What does mcpServers mean?

mcpServers is the top-level object that wraps all MCP server definitions in most clients. Each key inside it is a unique server name, and each value is a server configuration object. VS Code uses "servers" and Zed uses "context_servers" instead.

Is an MCP config valid JSON?

Yes. The file must be valid JSON: double quotes, no trailing commas, and escaped backslashes. Some clients like Zed allow JSONC, which permits comments, but the generated config from this tool is plain JSON.

Where do I put API tokens?

API tokens and other secrets go inside the env object as string values. Because they are stored in plaintext, keep the config file out of public git repos and screenshots.

Why does my config work in Zed but not Claude Desktop?

Zed expects a "context_servers" object, while Claude Desktop expects "mcpServers". Using the wrong wrapper object is a common mistake when copying a config between clients.

Try the MCP Config Generator to produce a valid config, or compare stdio, SSE, and Streamable HTTP.