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. When the server needs sign-in, Zed shows an Authenticate button that runs the OAuth flow, then 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. OAuth for remote servers arrived in stable v0.230.0, so use that release or later.

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 Settings → AI → MCP Servers (or run agent: open settings, also in the Agent Panel's top-right menu), click Add Server, and choose Add Remote Server. Enter a name and the URL.

From settings.json: open your settings file (Cmd+Alt+, / Ctrl+Alt+,, or the zed: open settings file 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

When the server needs sign-in, Zed shows an Authenticate button for it (the Add Remote Server form runs this step inline). Click it and 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. Open Settings → AI → MCP Servers and check the dot next to the server — green, with the tooltip "Server is active", means it's 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 October 2026, and Zed's own agent is unaffected. Zed forwards its configured MCP servers to external agents over ACP, but OAuth-authenticated servers may not come through.

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, click Authenticate, approve in the browser, and the server's dot in Settings → AI → MCP Servers turns green. The account-holder walkthrough is in the Zed setup doc.