Where Zed’s MCP config lives, the context_servers format, the extension and UI install paths, and how to fix the common failures — plus how to put a policy gate in front of every tool call.
QUICK ANSWERQuick answer: MCP servers go under the context_servers key in Zed’s settings.json — not mcpServers.
| Scope | Path | Notes |
|---|---|---|
| User (macOS/Linux) | ~/.config/zed/settings.json | Linux also honours $XDG_CONFIG_HOME/zed/settings.json. |
| User (Windows) | %APPDATA%\Zed\settings.json | |
| Project | .zed/settings.json | At the project root; overrides user settings for that project. |
A top-level context_servers object, one entry per server. Local servers declare a command; remote servers declare a url.
| Key | What it does |
|---|---|
command | Executable for a local server. Zed launches without a full login shell — use an absolute path. |
args | Array of arguments passed to the command. |
env | Environment variables — set explicitly; GUI-launched Zed doesn’t inherit your shell env. |
url | Endpoint for a remote server. |
headers | HTTP headers for remote servers. Omit Authorization and Zed runs the standard MCP OAuth flow instead. |
{
"context_servers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
"env": {}
}
}
} REMOTE SERVER (HTTP):
{
"context_servers": {
"remote-mcp-server": {
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
} Leave out the Authorization header and Zed authenticates the remote server via the standard MCP OAuth flow.
| Transport | Status | How to declare it |
|---|---|---|
| stdio | Supported | Declare command + args. |
| Streamable HTTP | Supported | Declare url; header auth or OAuth. |
Open settings (zed: open settings) and add entries under context_servers — user-level or per-project in .zed/settings.json.
Run agent: open settings (or the Agent Panel’s settings view) → Add Custom Server — a modal collects the command or URL for you.
Install MCP servers as Zed extensions from the extension store — the extension ships the server config and appears under the same settings view.
agent.tool_permissions settings.Zed launches servers without a full login shell, so aliases and PATH additions from your dotfiles don’t apply. Use an absolute path to the binary.
GUI-launched Zed (Dock/Finder) doesn’t inherit your shell environment — set required variables explicitly in the server’s env block.
No Authorization header means Zed expects to complete an OAuth flow. For token-auth servers that don’t do OAuth, supply the header explicitly.
Check the key name — it’s context_servers, not mcpServers — and remember a project’s .zed/settings.json overrides your user file.
Tool approval is governed by agent.tool_permissions.default (Zed v0.224+), which replaced the old always_allow_tool_actions boolean — review it if calls behave unexpectedly.
A standard Postgres MCP wired into Zed. Every query hits the database directly, with no audit trail and no statement-level controls.
{
"context_servers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
"env": {}
}
}
} Register the Postgres MCP in PolicyLayer, mint a grant, point Zed at the proxy URL. PolicyLayer evaluates every call against the grant’s policy before it reaches the database.
{
"context_servers": {
"postgres": {
"url": "https://proxy.policylayer.com/mcp/<server-uuid>/",
"headers": {
"Authorization": "Bearer <grant-token>"
}
}
}
} The <server-uuid> appears on each server's detail page. The <grant-token> shows once at mint time. See the Quick start for the full setup walk-through — and if you operate under SOC 2, HIPAA, GDPR or similar, the compliance hub maps how gateway-mediated MCP traffic evidences each framework.
Allow list_tables. Allow queries, but deny any statement containing DROP, TRUNCATE or DELETE.
{
"version": "1",
"default": "deny",
"tools": {
"query": {
"deny_if": [
{
"conditions": [
{ "path": "args.sql", "op": "regex", "value": "(?i)(DROP|TRUNCATE|DELETE)\\s" }
]
}
]
},
"list_tables": {}
}
} See Writing policies for the policy format, operators, and quota shapes.
Under the context_servers key in settings.json — ~/.config/zed/settings.json on macOS/Linux, %APPDATA%\Zed\settings.json on Windows, or per-project in .zed/settings.json. Zed kept its original key name rather than adopting mcpServers.
Yes — declare a url, with auth either as an Authorization header or, if the header is omitted, via the standard MCP OAuth flow that Zed runs automatically.
The Agent Panel settings view shows an indicator dot per server — green with a “Server is active” tooltip when it is healthy. A non-green dot usually means a bad command path or a startup crash.
Zed launches servers without a login shell and, when started from the Dock, without your shell environment. Use absolute paths for the command and set env vars explicitly in the env block.
Via agent.tool_permissions.default in settings (Zed v0.224+). That is a client-side prompt, though — for deterministic rules on tool arguments, rate limits and audit logs, route the server through a policy gateway like PolicyLayer.
Route your MCP traffic through PolicyLayer. Every tool call is checked against your policy before it runs: allow, deny, or require approval. Per-identity grants. Full audit log. Live in minutes.
Instant setup, no code required.
46,500+ MCP servers and 515,000+ tools scanned and risk-classified.