How to Add an MCP Server to Zed

Zed is a high-performance open-source editor with a built-in agent panel, and it declares MCP (context) servers inside its main settings.json under a context_servers object. That wrapper name is the crucial difference from other clients: a config written for Claude Desktop uses mcpServers and does nothing in Zed until the key is renamed. Local servers use a flat command/args/env object, and the user-level settings path differs per platform.

Config file location

Generate a Zed config

The tool below is pre-set to Zed. Fill in the server and copy the JSON — it never leaves your browser.

Files are read locally; nothing is uploaded.

Working example

The same GitHub server in Zed format. Note the top-level key is context_servers, not mcpServers, and the local entry is a flat command/args/env object - the classic Zed migration mistake is leaving the old wrapper in place.

{
  "context_servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "<your-token-here>"
      }
    }
  }
}
settings.json (context_servers section)
{
  "context_servers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "<your-api-key-here>"
      }
    }
  }
}
Zed settings.json snippet showing the top-level context_servers object with a Brave Search server and a placeholder API key.

How to add the server, step by step

  1. Open Zed's settings.json (Command Palette > "zed: open settings file").
  2. Add a "context_servers" object at the top level if none exists.
  3. Paste your server entry inside it, keeping the rest of your settings intact.
  4. Save - Zed applies settings live, but restart the agent thread if a server looks stale.
  5. Open the agent panel and check that the server's tools are available.

Zed-specific pitfalls

The wrapper key is context_servers, not mcpServers

Most MCP examples on the web target Claude Desktop's mcpServers. Pasted into Zed's settings.json unchanged, the block is ignored without any error. Renaming the key to context_servers is the entire fix - the generator above already emits the Zed shape. An even older "mcp" key is legacy; the diagnose tab flags both mismatches as blocking errors.

Local entries are flat, not nested

In user settings.json a local server is a flat {"command": "...", "args": [...], "env": {...}} object. The nested command object you may see in Zed's extension documentation is the extension development API (Rust code), not the JSON users write.

Zed settings are JSONC

Zed accepts comments and trailing commas in settings.json, so a config that "works" in Zed can still break every other client you share it with. Keep the file strict-JSON clean if you copy configs between tools; our validator flags comments and trailing commas for portability.

The user-level path depends on your platform

There is no single cross-platform Zed settings path: Windows uses %APPDATA%\Zed\settings.json, macOS uses ~/Library/Application Support/Zed/settings.json, and Linux follows $XDG_CONFIG_HOME with a ~/.config fallback. When in doubt, run "zed: open settings file" from the Command Palette instead of guessing.

Related troubleshooting

Client compatibility matrix

context_servers side by side with the mcpServers and servers families, plus per-platform paths.

spawn ENOENT / npx not found

When the config is right but the server process never launches.

FAQ

Where do MCP servers go in Zed?

In Zed's settings.json, inside a top-level "context_servers" object. The user-level file is %APPDATA%\Zed\settings.json on Windows, ~/Library/Application Support/Zed/settings.json on macOS, and $XDG_CONFIG_HOME/zed/settings.json on Linux (falling back to ~/.config/zed/settings.json); projects can also carry .zed/settings.json. Each key is a server name and each value holds a flat command, args and env.

Why does my Claude Desktop config not work in Zed?

Claude Desktop wraps servers in "mcpServers", while Zed expects "context_servers". Rename the top-level key and the same server definitions work in Zed.

Does Zed reload MCP servers automatically?

Zed watches settings.json and applies changes on save. If a server misbehaves after an edit, start a new agent thread or restart Zed to force a clean launch of the server process.

Configuring other clients too? See the guides forClaude Desktop,Cursor,VS Code,Windsurf,Zed andCline, or readhow MCP transports differ.