Problem: Your Zed AI Agent Can't See Outside Your Editor

MCP servers in Zed are the only way to give the built-in AI agent access to external tools — databases, GitHub, filesystems, APIs — without leaving the editor. Without them, the agent is limited to what's in your open files.

You'll learn:

How Zed's context_servers config works under the hood
How to add MCP servers via settings.json and the Agent Panel UI
How to verify a server is live and fix the most common failure modes

Time: 15 min | Difficulty: Intermediate

Why Zed Handles MCP Differently

Zed implements MCP via its Agent Panel (not a sidebar chat like Cursor or Windsurf). Every tool call gets a per-action permission prompt unless you explicitly auto-approve. This design is intentional — Zed's philosophy is explicit over automatic.

There are two ways a server reaches Zed: as a packaged extension from the Zed marketplace, or as a custom entry in settings.json. Both end up in the same context_servers object. The difference is who manages the binary — Zed's extension host or you.

Current limitations to know upfront:

Zed supports MCP Tools and Prompts only — Resources and Sampling are not yet implemented
Remote/streaming HTTP MCP servers require the mcp-remote bridge package (stdio only natively)
Tool reliability varies by model — mentioning the server name in your prompt helps routing

Solution

Step 1: Open Your Zed Settings File

# macOS / Linux
# Open settings from the command palette
# Cmd+Shift+P → "zed: open settings"

# Or edit directly
code ~/.config/zed/settings.json   # replace "code" with your editor

The settings file is plain JSON. If it doesn't exist yet, Zed creates it on first open.

Expected: A JSON file that may already contain theme or keymap preferences.

Step 2: Add a Context Server Entry

Add the context_servers key at the top level of settings.json. Here's the filesystem server (ships with @modelcontextprotocol/server-filesystem on npm):

{
  "context_servers": {
    "filesystem": {
      "source": "custom",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects"
      ],
      "env": {}
    }
  }
}

The source: "custom" flag is required for any server you add manually. Without it, Zed treats the entry as malformed and silently skips it.

If it fails:

command not found: npx → Node 20+ is required; run node --version to check
Server shows red dot → Check the path passed as arg; it must be an absolute path you have read access to

Step 3: Add a Server That Requires an API Key

Most real-world MCP servers need credentials. Pass them through the env block — never hardcode them in args.

Here's the GitHub MCP server:

{
  "context_servers": {
    "filesystem": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"],
      "env": {}
    },
    "github": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Zed reads env at server startup and passes it to the child process. The token never appears in the Agent Panel UI.

Step 4: Connect a Remote MCP Server via `mcp-remote`

Zed only supports stdio transport natively. For servers that speak streaming HTTP (most hosted MCP services), use mcp-remote as a local bridge:

{
  "context_servers": {
    "my-remote-server": {
      "source": "custom",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.example.com/mcp",
        "--header",
        "Authorization:Bearer YOUR_API_KEY"
      ],
      "env": {}
    }
  }
}

mcp-remote starts a local stdio proxy that forwards calls to the HTTP endpoint. This is the current recommended workaround until Zed ships native streaming HTTP support.

Step 5: Install Extension-Based MCP Servers (Optional Alternative)

For servers that have a packaged Zed extension, skip settings.json entirely:

Open the Agent Panel (Cmd+Shift+A or agent: open agent panel)
Click the top-right menu → View Server Extensions
Find and install the extension (e.g., GitHub, Postgres, Brave Search)
Zed will display a setup modal prompting for any required tokens or config

Extension-managed servers auto-update and handle binary downloads. Use this path when available.

Verification

After saving settings.json, Zed restarts the context server process automatically (no editor restart needed).

Check server status:

Open the Agent Panel (Cmd+Shift+A)
Click the settings icon (top-right gear)
Look at the status dot next to each server name

Dot color	Meaning
🟢 Green	Server is active and tools are loaded
🟡 Yellow	Server is starting or reconnecting
🔴 Red	Server failed — check logs

Check logs if a server shows red:

# From command palette
# Cmd+Shift+P → "zed: open logs"
# Look for lines mentioning your server name

Test a tool call:

Open the Agent Panel and type:

Using the filesystem server, list the files in my projects directory

You should see a permission prompt followed by a tool result. Click Allow to approve.

Configure Tool Permissions

By default, Zed prompts before every tool action (confirm mode). For servers you trust completely, switch to auto-approve:

{
  "agent": {
    "always_allow_tool_actions": true
  }
}

For per-tool granularity, use the tool_permissions key. MCP tools follow the format mcp:<server>:<tool_name>:

{
  "tool_permissions": {
    "mcp:filesystem:read_file": "allow",
    "mcp:filesystem:write_file": "confirm",
    "mcp:github:create_issue": "confirm"
  }
}

This lets you auto-approve read operations while keeping destructive writes gated.

What You Learned

context_servers in settings.json is the core config — source: "custom" is required for manual entries
API keys go in env, not args, and never appear in the UI
mcp-remote is the current bridge for HTTP-based MCP servers; native HTTP support is in progress
Tool permissions are per-tool via mcp:<server>:<tool_name> — default is confirm
Extension-installed servers are simpler to maintain if the server has a published Zed extension

Limitation: Zed doesn't yet support MCP Resources or Sampling. If your server relies on these features, you'll need Cursor or a standalone MCP client until Zed's coverage expands.

Tested on Zed 0.178+, Node 22, macOS Sequoia and Ubuntu 24.04

FAQ

Q: How do I add an MCP server in Zed without editing settings.json? A: Open the Agent Panel → settings view → click "Add Custom Server." The modal accepts the same command, args, and env fields — it writes the JSON to settings.json on save.

Q: What is the difference between source: "custom" and extension-based MCP servers in Zed? A: Extension-based servers are packaged and installed via Zed's extension marketplace; Zed manages their binaries and updates. Custom servers point to a command you provide — useful for local development servers, private tools, or any server not yet packaged as an extension.

Q: Does Zed support MCP on Windows? A: Yes. The settings.json path is %APPDATA%\Zed\settings.json and the context_servers config works identically. Use PowerShell-style absolute paths for filesystem server args (e.g., C:\\Users\\yourname\\projects).

Q: Can I run multiple MCP servers in Zed at the same time? A: Yes. Add multiple keys to context_servers — each runs as a separate child process. Zed loads all tool lists into the Agent Panel and the model can call tools from any active server within a single conversation.