MCP server in Zed editor

context_servers configuration format

Add context_servers to Zed's global settings.json (open with Zed → Settings → Open Settings) or to a project's .zed/settings.json for project-scoped servers:

// ~/.config/zed/settings.json — global Zed settings
{
  "context_servers": {
    "my-api-server": {
      "source": {
        "type": "url",
        "url": "https://api.example.com/mcp"
      },
      "settings": {
        "api_key": "${MY_API_KEY}"
      }
    },
    "local-dev-tools": {
      "source": {
        "type": "url",
        "url": "http://localhost:3000/mcp"
      }
    },
    "stdio-tools": {
      "source": {
        "type": "binary",
        "command": "node",
        "args": ["/path/to/server/dist/index.js"]
      },
      "settings": {}
    }
  }
}

The context_servers key uses a named-server map identical in concept to .vscode/mcp.json, but with a different schema. Each server entry has two fields:

Zed loads context_servers at startup. To reload after editing settings, use Zed: Reload Extensions from the command palette or restart Zed.

HTTP transport configuration

For HTTP servers (including locally hosted development servers), use "type": "url":

"context_servers": {
  "project-tools": {
    "source": {
      "type": "url",
      "url": "https://mcp.myproject.example.com/mcp"
    },
    "settings": {
      "workspace_id": "proj-alpha",
      "environment": "production"
    }
  },
  "staging-tools": {
    "source": {
      "type": "url",
      "url": "https://staging.mcp.myproject.example.com/mcp"
    },
    "settings": {
      "workspace_id": "proj-alpha",
      "environment": "staging"
    }
  }
}

Zed connects to the URL using the MCP Streamable HTTP transport. It sends initialize via HTTP POST, then establishes a GET connection for server-sent events. If your server does not implement the SSE GET endpoint, Zed falls back to polling-based message retrieval. Implement both POST and GET endpoints for full compatibility.

Authentication headers are not natively configurable in Zed's context_servers schema (unlike VS Code's headers field). The recommended approach for authenticated HTTP MCP servers in Zed:

1. Expose the server on localhost via a local stdio proxy that handles authentication and forwards to the remote HTTP server
2. Use an environment variable in the server process for the API key and read it at request time (process.env.MCP_API_KEY)
3. For team-shared servers, use IP allowlist or mTLS rather than bearer token authentication to avoid per-developer key management

Stdio transport configuration

For locally running MCP servers launched as subprocesses, use "type": "binary":

"context_servers": {
  "local-search": {
    "source": {
      "type": "binary",
      "command": "node",
      "args": [
        "/Users/dev/projects/search-mcp/dist/index.js",
        "--index", "/Users/dev/search-index"
      ]
    },
    "settings": {
      "max_results": 20
    }
  },
  "python-tools": {
    "source": {
      "type": "binary",
      "command": "/Users/dev/.pyenv/versions/3.12.0/bin/python",
      "args": ["-m", "my_mcp_server"],
      "env": {
        "DATABASE_URL": "postgres://localhost:5432/dev",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Note: the env key under source for binary-type servers is available in newer Zed versions. For older versions, environment variables must be set at the system level (via .zshrc / .bashrc) because Zed launches stdio subprocesses inheriting its own environment, which on macOS includes the GUI application environment rather than the shell environment. If your stdio MCP server needs shell-defined environment variables, launch Zed from the terminal (zed .) rather than from Spotlight or Dock, or use a wrapper script that sets environment variables explicitly:

#!/bin/bash
# /usr/local/bin/my-mcp-launcher
export DATABASE_URL="postgres://localhost:5432/dev"
export API_KEY="$(cat ~/.secrets/my-api-key)"
exec node /path/to/my-mcp-server/dist/index.js "$@"

"context_servers": {
  "my-server": {
    "source": {
      "type": "binary",
      "command": "/usr/local/bin/my-mcp-launcher"
    }
  }
}

Tools in the Zed AI assistant panel

After Zed connects to a configured MCP server, discovered tools appear in the assistant panel. Open the assistant with Cmd+? (macOS) or Ctrl+? (Linux/Windows). A tools indicator in the panel header shows how many tools are available from connected servers.

Unlike VS Code (which requires the user to switch to "agent mode" to access MCP tools), Zed's assistant is always in tool-capable mode when context servers are connected. The LLM decides whether to call a tool based on your message — you do not need to switch modes or explicitly invoke tools.

Zed's tool invocation flow:

1. You send a message to the assistant
2. Zed includes all registered tool schemas in the system prompt sent to the LLM
3. The LLM returns a response that includes a tool call (if appropriate)
4. Zed shows the proposed tool call in the chat with an inline approval prompt
5. You click Run to execute the tool call
6. The tool result is appended to the conversation and the LLM generates its final response

Zed's approval step is similar to VS Code's: the developer must explicitly allow each tool call. Unlike VS Code, Zed does not have a "always allow" persistent permission for MCP tools — each session starts fresh. This is a security-conscious design choice that prevents a malicious workspace settings file from permanently granting a tool the ability to run without prompt.

Project-level context server configuration

Zed supports project-level settings in .zed/settings.json at the workspace root. Project-level context servers merge with global context servers — if the same server name appears in both, the project setting overrides the global one:

// .zed/settings.json — project-specific context servers
{
  "context_servers": {
    "project-specific-tools": {
      "source": {
        "type": "url",
        "url": "http://localhost:4000/mcp"
      },
      "settings": {
        "project_root": "/path/to/project",
        "schema_version": "2"
      }
    }
  }
}

Project-level .zed/settings.json is typically committed to git — it's the Zed equivalent of VS Code's .vscode/mcp.json. For team use, avoid putting secrets in this file. Unlike VS Code, Zed does not have a built-in input variable substitution mechanism for context servers — use environment variables via wrapper scripts or a local credential management tool instead.

Debugging MCP connections in Zed

Zed logs MCP protocol activity to its application log file. Access it via View → Debug → Open Log File (or search for "Log" in the command palette). The log includes the full JSON-RPC exchange for all context server connections:

[2026-06-26T14:23:01Z INFO] ContextServer "project-tools": connecting to http://localhost:4000/mcp
[2026-06-26T14:23:01Z DEBUG] → {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"Zed","version":"0.148.0"},"capabilities":{"tools":{}}}}
[2026-06-26T14:23:01Z DEBUG] ← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","serverInfo":{"name":"project-tools","version":"1.0.0"},"capabilities":{"tools":{}}}}
[2026-06-26T14:23:01Z DEBUG] → {"jsonrpc":"2.0","id":2,"method":"tools/list"}
[2026-06-26T14:23:01Z DEBUG] ← {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"search","description":"Search the project codebase","inputSchema":{"type":"object","properties":{"query":{"type":"string"}}}}]}}
[2026-06-26T14:23:01Z INFO] ContextServer "project-tools": connected, 1 tool(s) registered

Common failure patterns and their log signatures:

Differences from Claude Desktop and VS Code MCP clients

If your MCP server already works with Claude Desktop or VS Code, it will generally work with Zed — all three implement the same MCP protocol. However, there are a few behavioral differences to be aware of:

For MCP servers targeting multiple clients, test your server against Zed's MCP client specifically. The most common Zed-specific issues are: environment variable injection for stdio servers (Zed inherits GUI environment, not shell environment) and authentication headers for HTTP servers (not natively supported, requires a proxy or env-var-based approach).

Monitoring MCP servers used in Zed

When your MCP server goes down, Zed's assistant panel stops showing tools — but Zed displays no user-visible error. The tools icon in the assistant panel may still show a count from the last successful connection, or it may disappear silently. Developers notice only when they try to use a tool and it fails, or when the tool doesn't appear in the suggestion list.

AliveMCP probes your server every 60 seconds with a full protocol check — initialize + tools/list — and alerts you immediately when the handshake fails. This is especially important for project-level context servers committed in .zed/settings.json: every developer who opens the project depends on your server being available, and a team-wide outage will generate multiple confused Slack messages before anyone pinpoints the MCP server as the cause.

Further reading

• MCP server in VS Code — .vscode/mcp.json configuration and debugging
• MCP server in Claude Desktop — claude_desktop_config.json setup
• MCP server stdio transport — subprocess lifecycle and environment setup
• Debugging MCP servers — protocol traces, inspector, and runtime errors
• MCP server in Windsurf — Cascade AI and MCP tool configuration
• AliveMCP — continuous protocol monitoring for MCP servers