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 an mcp 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.

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.

Transport
Advanced: environment variables

Config JSON

Where this file lives

    Working example

    The same GitHub server in Zed format. Note the top-level key is mcp, not mcpServers - this is the single most common Zed migration mistake.

    {
  "mcp": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "<your-token-here>"
      }
    }
  }
}
    ~/.config/zed/settings.json
    {
  "mcp": {
    "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 mcp 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").
    2. Add an "mcp" 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 mcp, 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 mcp is the entire fix - the generator above already emits the Zed shape.

    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.

    Check extensions before hand-writing a server

    Zed ships several context servers as extensions, which install and update themselves. If an extension exists for your service, prefer it over a manual mcp entry - duplicate definitions of the same server lead to confusing double tool listings in the agent panel.

    One settings file, many concerns

    The mcp block lives beside your theme, keymap and language settings. A JSON typo anywhere in the file can make Zed discard all settings, MCP included. Validate the whole file after editing, not just the block you touched.

    FAQ

    Where do MCP servers go in Zed?

    In ~/.config/zed/settings.json, inside a top-level "mcp" object. Each key is a server name and each value holds command, args and env - the same fields as other clients, only the wrapper key differs.

    Why does my Claude Desktop config not work in Zed?

    Claude Desktop wraps servers in "mcpServers", while Zed expects "mcp". 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.