Zed Editor MCP Server Setup 2026: context_servers Configuration
Configure MCP servers in Zed editor's agent panel: the context_servers settings key, local stdio and remote HTTP JSON shapes, extension-based install, and how to open settings.json without guessing the file path.
Key Takeaways
context_servers key in Zed's own settings.json — not a separate MCP-specific file.command/args/env) and remote servers (url plus headers for auth), so a hosted MCP endpoint with a bearer token works the same as a locally spawned process.cmd-, on macOS, ctrl-, on Windows/Linux) — Zed's settings file location has moved between versions, so opening it through the editor beats hardcoding a path.notifications/tools/list_changed notification, so a server that adds tools at runtime doesn't need a manual restart to pick them up.Two ways to add a context server
Through the UI: Settings → AI → MCP Servers, then Add Server, which offers Install from Extensions (browse the marketplace) or manual Add Local Server / Add Remote Server options.
Through JSON directly: open the command palette and run agent: open settings, then select MCP Servers, or run zed: open settings file to edit settings.json directly. Both land you at the same underlying configuration.
The context_servers JSON shapes
Local server (stdio):
{
"context_servers": {
"server-name": {
"command": "some-command",
"args": ["arg-1", "arg-2"],
"env": {}
}
}
}
Remote server (HTTP, with auth header):
{
"context_servers": {
"remote-server": {
"url": "https://example.com/mcp",
"headers": { "Authorization": "Bearer <token>" }
}
}
}
The headers field is what makes remote servers with bearer-token auth workable directly in Zed's own settings file, without a separate proxy — put the token there rather than trying to embed it in the URL.
Step 1: Open your settings file
Press cmd-, (macOS) or ctrl-, (Windows/Linux) to open Zed's settings directly, or run zed: open settings file from the command palette. Zed's settings location has shifted across versions and differs by platform, so opening it through the editor is more reliable than typing a path from memory — let Zed find its own file rather than guessing.
Step 2: Add a local context server
For a locally-run MCP server, add a context_servers block with command/args. A filesystem server is a reasonable first test:
{
"context_servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/your/project"],
"env": {}
}
}
}
Save the file. Zed picks up context_servers changes without requiring a full editor restart in most cases.
Step 3: Add a remote context server
For a hosted MCP endpoint that needs a bearer token:
{
"context_servers": {
"example-remote": {
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN_HERE"
}
}
}
}
Step 4: Or skip the JSON with the extension marketplace
Run zed: extensions from the command palette, or go to Settings → AI → MCP Servers → Add Server → Install from Extensions, and filter for context servers. Many common MCP integrations are published as Zed extensions, which install and configure the server without you writing command/args/env by hand — worth checking before manually configuring something popular, since the extension version is often kept current by its maintainer.
Step 5: Verify
Open Zed's agent panel and start a conversation. Ask something that requires the new server's tools:
List the files in this project using the filesystem context server.
If the assistant calls the tool and returns real results, the server connected. Zed's agent panel also reflects new tools automatically if the server sends a notifications/tools/list_changed update after you add tools at runtime — you shouldn't need to restart Zed just because a running server's tool list changed.
Running multiple context servers
Add as many keys as you need under context_servers — each runs as its own process (for local servers) or its own connection (for remote servers), and all of them contribute tools to the same agent panel conversation:
{
"context_servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
},
"example-remote": {
"url": "https://mcp.example.com/mcp",
"headers": { "Authorization": "Bearer YOUR_TOKEN_HERE" }
}
}
}
The model chooses which server's tools to call based on the prompt — you don't need to tell Zed which server to use for a given question.
Troubleshooting
Settings file edit doesn't seem to do anything. Confirm you edited the file Zed actually opened via cmd-, / ctrl-, or zed: open settings file — if you found and edited a settings.json at a path you looked up separately, it may not be the one Zed is reading on your system and version.
Local server fails to start. Run the exact command and args in a terminal outside Zed first. If it errors there, Zed spawning it will fail the same way — fix the standalone invocation before assuming it's a Zed-specific problem.
Remote server connects but every call fails with an auth error. Check that the token is in headers.Authorization in the format the server expects (commonly Bearer <token>), and that it hasn't expired. A URL-embedded token, if you're used to that pattern from another tool, isn't the shape Zed's context_servers uses — use headers instead.
Installed an extension-based context server but don't see its tools. Confirm the extension is enabled (Settings → AI → MCP Servers should list it as active), and that any credentials the extension itself requires were entered during its setup flow — an installed-but-unconfigured extension can appear present without actually connecting.
New tools from a running server aren't showing up. Zed relies on the server sending notifications/tools/list_changed to know to refresh. If the server doesn't send that notification when its tool list changes, Zed won't know to reload — restarting the context server (or Zed itself) forces a fresh tool list either way.
Frequently Asked Questions
Q: Is Zed's MCP support the same JSON format as Claude Desktop or Cursor?
A: Close but not identical. Zed uses a context_servers top-level key instead of mcpServers, and the field names inside each entry (command/args/env for local, url/headers for remote) are Zed's own shape — copy the structure, not a literal mcpServers block from another client.
Q: Do I have to write JSON by hand to add a context server in Zed?
A: Not necessarily. Zed's extension marketplace has a context-server category — Settings → AI → MCP Servers → Add Server → Install from Extensions covers many popular servers without manual JSON.
Q: Can a remote MCP server that needs a bearer token work directly in Zed, or do I need a local proxy?
A: Directly. The remote server JSON shape includes a headers field specifically for this, so Authorization: Bearer <token> goes straight into the context_servers entry.
Q: Where exactly is Zed's settings.json on my system?
A: Don't hardcode it — the location differs by platform and has moved across Zed versions. Use cmd-, / ctrl-, or the zed: open settings file command palette action to have Zed open the correct file for your install directly.
Q: Do I need to restart Zed every time a context server's tools change?
A: Not if the server sends the standard notifications/tools/list_changed update — Zed's agent panel reloads the tool list automatically on that signal. If a server doesn't send it, restarting the server or Zed is the fallback.