To add an MCP server to Zed, open Agent Settings, choose MCP Servers, click Add Server, and select an installation route: install a listed extension, add a local command, or add a remote URL. Configure the server, confirm the green Server is active indicator, then use the server from Zed Agent. External Agents can receive Zed’s configured servers over ACP, while terminal threads usually use the MCP configuration of their own CLI or TUI.
What Zed’s MCP integration supports
Zed uses the Model Context Protocol to interact with context servers. Its documented MCP support includes Tools and Prompts. Zed also handles the notifications/tools/list_changed notification, so it can reload a server’s tool list when the server reports that its available tools changed.
Discovery, Sampling, and Elicitation are areas where Zed’s documentation welcomes additional feature coverage. Do not assume that a server exposing one of those capabilities will work in Zed simply because it supports MCP; verify the capabilities it requires.
Open the MCP Servers page
- Open the Command Palette and run
agent: open settings. You can also runzed: open settings, then select AI. - In Agent Settings, find the MCP Servers section. The AI settings page also contains separate sections for LLM Providers and External Agents.
- Click Add Server. Choose Install from Extensions, Add Local Server, or Add Remote Server.
The route you choose determines who owns the process and where credentials are entered. Extensions are packaged and discoverable through Zed; local servers are processes that Zed starts; remote servers are services reached over a URL.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match#1 Best Overall
Route 1: Install an MCP server from Extensions
Install from Agent Settings
- Open AI → MCP Servers.
- Click Add Server → Install from Extensions.
- Select the server and complete the extension installation flow.
- Return to MCP Servers and check its status indicator.
Install through the Extensions view
Open the Command Palette and run zed: extensions, or open Zed’s Extensions view from the application interface. Search for the server, install it, and then confirm that it appears under MCP Servers.
Zed’s documentation gives Context7, GitHub, Puppeteer, Gem, Brave Search, Prisma, Framelink Figma, and Resend as examples of popular extension servers. Availability can change, so treat the Extensions view as the current catalog rather than assuming every example is available in every release.
When the extension route is best
- Use it when the provider has already packaged configuration for Zed.
- Use it when you want discovery and installation inside Zed instead of maintaining a command yourself.
- Choose another route when you need a private build, unusual command-line arguments, custom environment variables, or a provider that is not listed.
Route 2: Add a local MCP server
A local server is started by Zed on your computer. You need the executable command, any arguments required by the provider, and any environment variables used for tokens or other settings.
Configuration shape
Zed stores local servers in a context_servers object. This example shows the documented fields; replace the command and arguments with the values required by your server provider.
{
"context_servers": {
"local-mcp-server": {
"command": "some-command",
"args": ["arg-1", "arg-2"],
"env": {}
}
}
}Configure it in Zed
- Open AI → MCP Servers and choose Add Local Server.
- Give the server a recognizable name.
- Enter the provider’s executable in command.
- Add each command-line argument in order under args, if the provider requires them.
- Add environment variables under env. Keep tokens out of source files and prompts; use the environment-variable name expected by the provider.
- Save the configuration and watch the server’s status dot.
Do not put shell syntax into command unless the provider explicitly requires a shell. If a server is normally launched through a package runner, configure the complete command and arguments exactly as its provider documents, and first verify that the same command starts successfully in a terminal.
Local-server checks
- The command must be installed and available to the environment in which Zed runs.
- Arguments must be separate entries, not one unparsed string, when the UI or configuration expects an array.
- Environment-variable names and values must match the provider’s documentation.
- Read the provider’s logs when the process exits immediately or reports a protocol error.
Route 3: Add a remote MCP server
A remote server is identified by a URL. Add an authorization header when the provider gives you one. If you do not configure an Authorization header, Zed says it will prompt for the standard MCP OAuth flow.
Rank #2
Bearer-token configuration
{
"context_servers": {
"remote-mcp-server": {
"url": "https://example.com/mcp",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}Replace the URL and token format with the provider’s exact values. A provider might require a different header name or scheme; do not assume every service accepts a bearer token.
OAuth configuration
{
"context_servers": {
"remote-mcp-server-with-oauth": {
"url": "https://mcp.example.com/mcp"
}
}
}After saving a URL without an Authorization header, follow Zed’s OAuth prompt. Complete authorization in the account and browser flow presented by the provider, then return to Zed and check the status dot.
When remote is preferable
- Choose remote when the provider hosts the runtime and you only need an endpoint and credentials.
- Choose local when data must stay on the workstation, the server is under your control, or you need custom startup flags.
- For either route, confirm the provider’s authentication, rate limits, and supported MCP operations before relying on it in an automated workflow.
Verify that the server is active
Return to AI → MCP Servers after installing or editing a server. Inspect the status dot and hover it. A green dot with the tooltip Server is active is Zed’s first configuration check: the server is running and available to Zed.
Any other state is a diagnostic signal, not proof that the MCP implementation is unusable. Start with the tooltip, then inspect the server provider’s logs and error documentation. Check the command, URL, credentials, and network access before changing unrelated settings.
Use MCP tools from Zed Agent
- Open the Agent Panel.
- Start or select an agent thread.
- Ask for work that requires the server’s capability. If automatic selection does not occur, name the MCP server explicitly in your prompt.
- Review the tool call and its parameters before allowing an operation that changes files, accounts, or external data.
Automatic tool selection can vary by model. Naming the server helps the model identify the intended capability, but it does not replace permission review or provider-side validation.
Make tool selection predictable with a custom profile
Create a custom agent profile when built-in tools conflict with the workflow or when you want a narrower tool set. Turn off conflicting built-in tools and turn on the MCP tools you need. This makes the available choices more predictable than relying entirely on automatic selection.
Recommended Free Tools
Understand Zed’s agent boundaries
| Agent path | How MCP configuration is obtained | Practical implication |
|---|---|---|
| Zed Agent | Uses MCP servers configured in Zed. | Configure and verify the server in Zed’s MCP Servers page. |
| External Agents | Can receive configured servers over ACP. | Confirm that the external agent supports the ACP handoff and that the intended server is passed through. |
| Terminal threads | Generally read their own native CLI or TUI MCP configuration. | A server configured in Zed may not automatically appear in a terminal tool; configure that tool separately. |
This boundary explains a common symptom: a server is green in Zed, yet a terminal-based agent cannot see it. The two paths may be reading different configuration stores.
Troubleshoot a server that is not active
The status dot is not green
Hover the dot and read the tooltip first. Check whether the local command exists, whether its arguments are valid, whether required environment variables are present, or whether the remote URL is reachable. Then consult the server’s own logs and provider documentation.
The local process exits immediately
Run the provider’s documented command outside Zed. Fix missing runtimes, packages, permissions, or required arguments there first. Copy the working command and arguments into Zed without adding shell quoting that the configuration parser does not expect.
The remote server asks for credentials repeatedly
Verify the URL, header name, token scheme, and token expiry. If you intentionally omitted an Authorization header, complete the standard MCP OAuth flow that Zed presents. A token issued for a different endpoint or audience will not authenticate the intended server.
The server is active but no tool appears
Ask the provider whether it exposes MCP Tools, rather than only another capability. Check for tool-list changes and restart or reconnect if the provider recently changed its tools. Zed supports the notifications/tools/list_changed notification, but a broken server notification or provider-side failure can still prevent a usable list.
The agent chooses the wrong tool
Name the MCP server in the prompt. If ambiguity remains, create a custom profile that disables conflicting built-in tools and enables the MCP tools required for the task. Model behavior affects automatic selection, so an active server does not guarantee that every model will call it automatically.
Rank #4
A tool call fails after discovery
Separate discovery from execution. An active server can still return invalid tool parameters, server-side failures, rate-limit responses, or unsupported-operation errors. Read the tool’s schema, reduce the request to a minimal valid call, and check provider limits and logs.
Zed Agent works but a terminal thread does not
Configure the MCP server in the terminal agent’s native CLI or TUI settings. Terminal threads generally do not inherit Zed’s MCP configuration automatically.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Security and reliability practices
- Store credentials in environment variables or the provider’s OAuth mechanism rather than embedding long-lived secrets in prompts.
- Use the narrowest server and tool set needed for a task.
- Review destructive tool calls before approval, especially when a server can write files, send messages, or change cloud resources.
- Keep local server runtimes and packages updated according to their providers’ guidance.
- For remote services, plan for authentication expiry, network failures, provider rate limits, and service-side maintenance.
- Use a custom profile for repeatable workflows where tool selection must be constrained.
Or skip the browser setup
If your MCP project needs website screenshots for an agent or test workflow, ScreenshotNeo provides an MCP server as well as a one-request screenshot API. Its cleanup step accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the result with X-Page-Verdict and X-Billed headers.
Use the MCP tool take_screenshot, get_page_info, or capture_pdf from Claude, Cursor, or another MCP client. If you prefer HTTP, this is a complete cURL request (see the ScreenshotNeo documentation for options):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The API supports PNG, JPEG, WebP, and PDF output plus full-page lazy-image loading, CSS-selector element capture, dark mode, device presets, arbitrary viewports, retina scale, PDF paper and margin controls, custom CSS and JavaScript, clicks, selector or network-idle waits, request and resource blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, selectable cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Parameter names used by other screenshot APIs also work, which can simplify migration.
There is a free allowance of 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan, and yearly billing gives two months free. Create a free ScreenshotNeo account.
Free tools Windows power users keep installed
One-click scans. No signup required.
FAQ
Does Zed support MCP resources, sampling, or elicitation?
The documented support covered here is MCP Tools and Prompts. Zed identifies Discovery, Sampling, and Elicitation as areas for additional feature coverage, so verify compatibility with the specific server you plan to use.
Can one MCP configuration serve every agent in Zed?
No. Zed Agent uses Zed’s configuration, External Agents can receive configured servers over ACP, and terminal threads generally use their own native CLI or TUI configuration.
What should I do when a provider changes its tool list?
Zed handles the notifications/tools/list_changed notification and can reload the list. If the list remains stale, inspect the provider logs and reconnect the server.
Frequently Asked Questions
Can I configure both local and remote MCP servers at once?
Yes. Add separate entries under context_servers, giving each a unique name and using either command/args or url/headers as appropriate.
Why does naming the server in my prompt help?
Automatic tool selection varies by model. Naming the server gives the agent an explicit routing hint; a custom profile can constrain the available tools further.
The Bottom Line
Configure MCP under AI → MCP Servers, choose the extension, local, or remote route that matches your ownership and authentication needs, and do not proceed until the status tooltip says Server is active. Then account for the separate configuration boundaries of Zed Agent, External Agents, and terminal threads.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
