How to Add a Remote MCP Server to Zed

How do I add a remote MCP server to Zed?

Add a context_servers block to your settings.json with the server's name and its url — that is the entire configuration. No headers, no tokens, no keys. Zed runs the OAuth flow as soon as it connects, stores the tokens in your system keychain, and refreshes them automatically. Settings hot-reload, so there is no restart. MCP is not gated by any plan, and it works on macOS, Linux, and Windows.

This is one of the cleanest MCP setups of any client, which makes its two failure modes worth knowing precisely, because neither is about the config being wrong.

Adding the server

Two equivalent paths.

From the UI: open the Agent Panel, then use its settings menu to add a remote MCP server — also reachable via Settings → AI → MCP Servers. Enter a name and the URL.

From settings.json: open your settings (Cmd+, / Ctrl+,, or the zed: open settings command) and add:

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

Note the key name: context_servers, not mcpServers. Zed uses its own vocabulary here.

Authorization, and the field that disables it

Zed prompts the OAuth flow as soon as it connects: a browser tab opens to the server's consent screen, you approve, and Zed stores the tokens in your system keychain and refreshes them automatically. You should not need to authorize again.

Leaving the Authorization header out is what triggers this. Zed's docs scope the rule to exactly that: when a remote server has no configured Authorization header, Zed prompts the standard MCP OAuth flow — so supplying one (say, speculatively while debugging) makes Zed skip OAuth entirely. If the OAuth prompt never appears, a configured Authorization header is the first thing to remove.

Verifying

Settings hot-reload, so there is nothing to restart. Check the server's status in the Agent Panel — it should show as connected — then ask the agent what tools it has access to.

What usually goes wrong

• The OAuth prompt never appears. A configured Authorization header is present. Remove it, save, reconnect.
• The server shows an error state. Settings hot-reload on save, so fix the JSON — a stray comma is the usual cause — and the server reconnects on its own.
• Connection fails immediately. Check the URL against exactly what the server publishes, including the path and any trailing slash.
• Tools work in Zed's agent but not in an external agent. See below — this one is not your config.

The ACP gap

If you drive an external agent inside Zed through ACP — for example running a terminal agent in the Agent Panel — tools from OAuth-authenticated servers may not appear. This is a known Zed issue, still open as of August 2026, and Zed's own agent is unaffected.

The distinction matters because the symptom looks exactly like a broken connection when nothing is broken. The fix is not to re-check your context_servers block; it is to connect the server directly inside that external tool, using that tool's own MCP configuration.

A worked example

With a real server — Tempreon, a hosted MCP server that carries your context between tools:

{
  "context_servers": {
    "tempreon": {
      "url": "https://api.tempreon.com/functions/v1/tempreon-mcp/mcp"
    }
  }
}

Save, approve in the browser, and the Agent Panel shows it connected. The account-holder walkthrough is in the Zed setup doc.