---
title: "Zed MCP Setup with ToolPiper on Mac"
description: "Connect Zed editor to ToolPiper's local MCP server through settings.json. Over 300 local tools available inside Zed's AI assistant."
date: 2026-05-16
author: "Ben Racicot"
tags: ["Zed", "MCP", "Model Context Protocol", "Setup Guide", "Privacy", "macOS"]
type: "article"
canonical: "https://modelpiper.com/blog/zed-editor-mcp-setup/"
---

# Zed MCP Setup with ToolPiper on Mac

> Connect Zed editor to ToolPiper's local MCP server through settings.json. Over 300 local tools available inside Zed's AI assistant.

## TL;DR

Zed supports MCP servers through its settings.json. Add a toolpiper entry under context_servers (or experimental.context_servers, depending on your Zed version) pointing at http://127.0.0.1:9998/mcp. Reload Zed. ToolPiper's over 300 tools become available to Zed's assistant.

Zed's MCP support was added in late 2024 and lives under the `context_servers` key in your settings. Zed calls them "context servers" rather than "MCP servers", but the underlying protocol is the same. ToolPiper drops in as one.

## How do I add ToolPiper to Zed?

Open Zed settings (Cmd-, or Zed menu -> Settings). Add a `context_servers` object with a `toolpiper` entry pointing at `http://127.0.0.1:9998/mcp`. Save. Zed reloads context server registrations automatically.

The minimum JSON to add:

```
{
  "context_servers": {
    "toolpiper": {
      "command": null,
      "url": "http://127.0.0.1:9998/mcp",
      "transport": "http"
    }
  }
}
```

Older Zed versions nest this under `experimental.context_servers` instead of the top-level key. Check the Zed changelog or your version's documentation to confirm. The field name is the only difference. The value shape is the same.

If your `settings.json` already contains other settings, add `context_servers` alongside them at the top level. JSON keys can appear in any order.

## Where does Zed's settings.json live?

On macOS, the user-level settings file is at `~/.config/zed/settings.json`. Project-level settings live at `.zed/settings.json` inside the project root and override the user-level config for that project.

Pick user-level for ToolPiper, since you usually want it everywhere. Project-level makes sense if you want different MCP servers in different repos.

If `~/.config/zed/settings.json` doesn't exist yet, create it with the JSON above. Zed creates the file the first time you save settings, but you can create it manually.

## How does Zed's assistant call ToolPiper tools?

Zed's assistant treats registered context servers' tools as part of its tool catalog. The model decides when to call a tool based on the conversation. You can also reference tools explicitly with @-mentions in some Zed versions.

Once registered, ToolPiper tools appear when you start an assistant conversation. The assistant sees the tools at session start. If you change `settings.json` mid-session, reload the window (Cmd-Shift-P -> "Reload") to pick up the new tools.

End-to-end test: open the assistant, ask _"take a screenshot of my screen"_. If Zed invokes `vision_screenshot` through ToolPiper, the wiring is correct.

## What if Zed can't see ToolPiper?

Three checks. ToolPiper is running. The settings.json is valid JSON in the right schema. Zed reloaded after the change. Each builds on the previous.

1.  ToolPiper running. `curl http://127.0.0.1:9998/health` returns a JSON response with `"status": "ok"`.
2.  Settings valid. Validate `settings.json` through any JSON linter. Zed surfaces invalid config in its log (View -> Toggle Logs).
3.  Zed reloaded. Either reload the window or restart Zed. Newer versions hot-reload context servers. Older ones require a window reload.

If all three pass and tools still don't appear, check whether your Zed version's MCP schema matches what you wrote. The `context_servers` key was promoted from experimental at a specific Zed version. If your version is older, you need `experimental.context_servers` instead. Older still, and MCP support isn't there.

For setup on other editors, see [MCP Setup on Mac](/blog/mcp-setup-guide-mac).

## FAQ

### Does Zed call them MCP servers or context servers?

Context servers in Zed's terminology, but it's the same MCP protocol underneath. The naming reflects Zed's broader assistant design rather than a different protocol.

### Does Zed support stdio MCP servers?

Yes. Use the `command` field with the binary path and `args` for arguments, instead of `url` and `transport: "http"`. ToolPiper supports both transports. HTTP is simpler and the recommended path.

### Can I use multiple context servers in Zed?

Yes. Add multiple entries under `context_servers`. Each is a named server with its own URL or command. Zed's assistant sees the combined tool catalog.

### Why does Zed sometimes show "context server failed to start"?

Usually because ToolPiper isn't running, or the URL is wrong. Check the Zed logs (View -> Toggle Logs) for the specific error message. Common causes: connection refused (ToolPiper not running), HTTP 404 (URL missing `/mcp` suffix), or invalid response (Zed version too old to handle the response format).

### Does Zed work with ToolPiper's HTTP transport or stdio?

Both. HTTP is recommended for ToolPiper because the server is already a long-running app; pointing Zed at the existing HTTP endpoint is simpler than spawning a stdio bridge. Use stdio only if your Zed version doesn't yet support HTTP MCP.