How to Add MCP Servers to Zed (context_servers)
On this page
Why your server doesn't show up
You paste a JSON block from a server's README into Zed's settings and nothing appears in the Agent Panel. The usual reason: the README used mcpServers, and Zed looks for context_servers. Zed uses the older name "context server" for the same thing. Once the key is right, the rest of the shape is familiar.
Option 1: add a server from the settings screen
- Open Settings, then AI, then MCP Servers.
- Click Add Server.
- Pick Add Local Server for a program Zed starts on your machine, or Add Remote Server for a URL.
Zed writes the entry into your settings file. The settings screen is also where you check status later.
Option 2: write the JSON yourself
Open your settings file (run the zed: open settings action from the command palette) and add a context_servers object. This example has one local server, one remote server with a token and one remote server that signs in with OAuth:
{
"context_servers": {
"playwright": {
"command": "npx",
"args": ["-y", "@playwright/mcp@0.0.84"],
"env": {}
},
"github": {
"url": "https://api.githubcopilot.com/mcp/",
"headers": { "Authorization": "Bearer <your token>" }
},
"sentry": {
"url": "https://mcp.sentry.dev/mcp"
}
}
}A local server needs command and args, with optional env. A remote server needs url, with optional headers.
The third entry has no Authorization header, so Zed runs the standard MCP OAuth flow and prompts you to sign in the first time it connects. That's the better option whenever a server supports it, because there's no token sitting in your settings file.
Option 3: install a server as an extension
Some MCP servers are published as Zed extensions, which bundle the install and config for you. Browse them at zed.dev/extensions with the context servers filter, run the zed: extensions action, or choose Add Server, then Install from Extensions. An extension may still ask for an API key after it installs.
Check that it's running
Go back to Settings, AI, MCP Servers and look at the dot next to each server. A green dot with the tooltip "Server is active" means Zed started it and loaded its tools. Then open the Agent Panel and ask for something only that server can do.
If the dot isn't green, run the server's command in a terminal. An error such as a missing environment variable or an old Node version shows up right away there, which is faster than guessing.
Decide how much the agent can do on its own
By default, Zed asks before the agent runs a tool. Since Zed 0.224.0 this is controlled by agent.tool_permissions.default, which can be confirm (the default), allow or deny. Older versions used a single agent.always_allow_tool_actions setting, which defaults to false.
Keep the default confirm while you get to know a server. You'll see each tool call before it happens, which is the easiest way to learn what a server can do.
You can also limit which tools a server exposes in a given agent profile, using the context_servers section inside agent.profiles. That's handy when one server has many tools and you only want a few of them in a profile you use often.
Check yourself
Rename the key to context_servers. Zed doesn't read mcpServers.
If the server supports MCP OAuth, Zed prompts you to sign in through the browser. No token is stored in settings.
In Settings, AI, MCP Servers. A green dot with "Server is active" means it's running.