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.