All documentation
On this page
Set-up documentation
Connect your mailbox to Zed
Zed calls MCP servers context_servers, and leaving the headers block out is what triggers the sign-in. A token here stops the OAuth flow you wanted.
context_servers
url
The configuration
Zed calls MCP servers context servers, and the block in its settings is named accordingly. Nothing else in this section uses that key.
{
"context_servers": {
"work-mail": {
"url": "https://mcp.mailbox-mcp.com/db/mcp/YOUR-MAILBOX-KEY"
}
}
}There is also a UI route, which writes the same thing: Settings, AI, MCP Servers, then Add Server and Add Remote Server. The other two options there, Install from Extensions and Add Local Server, are for a different kind of server and are not what you want here.
Leaving headers out is the setting
This is the part to get right, and it is the opposite of an omission.
Zed's documentation says it plainly: when a remote MCP server has no
configured Authorization header, Zed prompts you to
authenticate against the server using the standard MCP OAuth flow.
So the empty space where a token would go is what triggers the sign-in.
Add a headers block with a bearer token in it and Zed will use
the token and never offer to sign you in, which is a worse arrangement:
you now have a long-lived credential sitting in a settings file, and you
chose the mailbox by pasting rather than by picking it from a list.
Where the wrong instruction comes from
Almost every generic MCP snippet on the internet carries a headers block, because most servers need one. Our own control panel printed one for Zed until 30 August 2026, when we read Zed's documentation properly and removed it. If you find a Zed snippet for this server with a token in it anywhere, it is out of date.
No type key either. None is documented for a remote entry, so
the config above is the whole of it.
Where settings.json lives
| System | Path |
|---|---|
| macOS | ~/Library/Application Support/Zed/settings.json |
| Linux | ~/.local/share/zed/settings.json |
| Windows | %LOCALAPPDATA%\Zed\settings.json |
All three are Zed's own, from its configuration documentation, rather than inferred from the other two.
Check that it worked
Try this first
Read the last email from whoever owns this project and tell me what they are waiting on.
Nothing is marked read by asking, so the message stays unread wherever you normally read your mail. If the server appears but every call fails, check the mailbox credential in the control panel rather than this file.
The free tier is 5 MCP calls a day on any mailbox, with no card, and Zed needs no token to use it.
Where to go next
Cursor and VS Code both use a different top-level key, so this block does not travel. The key table shows all of them together.
- Which Zed version added remote MCP support.
- Whether a remote entry accepts any type key at all. None is documented.
Read 30 August 2026 Every value on this page came off Zed documentation: Model Context Protocol on that day. If it has changed since, tell us and we will read it again.