Add a Remote MCP Server to Zed: context_servers and Fixes

Zed calls MCP servers context servers. A remote one is an entry with a url under context_servers in your settings file [1]:

{
  "context_servers": {
    "my-server": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

You do not have to type it. Open Settings > AI > MCP Servers (or run agent: open settings and pick MCP Servers), click Add Server, then Add Remote Server, and Zed writes this entry for you [1].

Everything below is checked against Zed's MCP documentation on 13 November 2026 [1].

TL;DR:

A remote entry is url plus optional headers. Those are the only two keys Zed documents for a remote server [1].
No Authorization header means OAuth. Zed prompts you to sign in with the standard MCP OAuth flow [1].
Every tool call asks first unless you change agent.tool_permissions [1].
A green dot means it is running. Any other colour has a tooltip that says what is wrong [1].

Add the server

The URL is the MCP endpoint itself, usually ending in /mcp, not the product's homepage or its docs page.

A server that takes an API key gets it in headers [1]:

{
  "context_servers": {
    "my-server": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

Zed's MCP page shows the token written straight into the file and does not describe reading it from an environment variable [1], so keep this entry out of any settings file you commit or share.

Zed handles notifications/tools/list_changed, so when a server adds or removes tools at runtime the list updates without a restart [1].

Leave the Authorization header out and Zed prompts you to authenticate against the server with the standard MCP OAuth flow [1]. Whether that works depends on what the server publishes: we read the authorization metadata of 169 servers that ask for credentials, from our registry census on 9 October 2026, and 162 offered Dynamic Client Registration [2]. MCP OAuth covers what a server has to publish for the sign-in to work.

Choose which tools run without asking

agent.tool_permissions.default sets what happens before any tool call, MCP tools included [1]:

Value	What it does
`"confirm"`	Asks before every tool action. The default
`"allow"`	Runs tool actions without asking
`"deny"`	Blocks every tool action

Rules for one tool use the key mcp:<server>:<tool_name>, such as mcp:github:create_issue [1]. In Zed v0.224.0 and later this replaces the old agent.always_allow_tool_actions setting [1].

To make the agent use one server's tools and nothing else, build a custom profile with "enable_all_context_servers": false and list that server's tools [1].

What Zed does not use yet

Zed supports the Tools and Prompts parts of MCP. Sampling, elicitation and discovery are not supported yet [1], so a server that depends on asking the user a question mid-call will not get that question shown in Zed.

When it will not connect

Zed's first signal is the dot next to the server in Settings > AI > MCP Servers: green with "Server is active" is working, anything else has a tooltip with the problem [1]. Tool errors show up in the agent's reply [1].

What you see	Usual cause	Fix
The dot is not green	The server did not start or connect	Hover the dot and read the tooltip [1]
No tools, or an error from the server	The URL is the homepage or docs page	Use the endpoint, usually ending in `/mcp`
`401` with a header set	Token wrong or expired	Replace it in `headers`
No sign-in prompt for a server that needs one	An `Authorization` header is set, so Zed skips OAuth	Remove the header [1]
Every call stops for approval	`tool_permissions.default` is `"confirm"`	Allow that tool with an `mcp:<server>:<tool>` rule [1]
A tool that asks you a question hangs or fails	Zed does not support elicitation yet	Use a client that does, or a tool that takes the answer as an argument [1]

For what the server's own error codes mean, see MCP server errors and MCP server connection failed.

Zed connects from your own machine, so a server on localhost or your VPN works for you and for nobody else. Our MCP connection test calls your server from our network, runs the handshake and tools/list, and reports what a stranger on the internet gets back, with a dated URL you can share. If it passes there and fails in Zed, the problem is in your settings, not the server.

The same setup in other clients is in Cursor, VS Code, JetBrains, Windsurf, Kiro, Warp, Claude Code, Codex, Claude Desktop and ChatGPT, and remote MCP server vs stdio covers whether your server should have a public address at all.