Zed MCP (context server) not working, or its tools missing: the fixes

Put the server under context_servers

Open settings.json with the zed: open settings file action, or go to Settings > AI > MCP Servers, click Add Server and pick Add Local Server or Add Remote Server. Either way the entry lands under context_servers. A local server takes command, args and env; a remote one takes url and, optionally, headers.

{
  "context_servers": {
    "my-local": {
      "command": "npx",
      "args": ["-y", "some-mcp-server"],
      "env": { "API_KEY": "..." }
    },
    "my-remote": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Read the status dot

Settings > AI > MCP Servers lists every server with a dot next to its name. Green, with the tooltip "Server is active", means Zed started it and has its tools. Any other color comes with a tooltip that says what went wrong; hover over it before changing anything. For a local server, run the same command and args in a terminal: if it fails there, it fails in Zed. The zed: open log action opens Zed's own log for the rest.

Remote servers: OAuth or a header, not both

• Zed starts the MCP OAuth sign-in only for a remote server with no Authorization header. Leave headers out to sign in in your browser.
• With an Authorization header set, Zed sends it and never prompts. A wrong or expired token then shows as a failed server, not as a sign-in prompt. Fix the token or delete the header to sign in instead.
• Use the server's final URL. A redirect to another host drops the header.

Active server, but the agent doesn't see its tools

• Profiles under agent.profiles decide which tools a chat gets. A profile with "enable_all_context_servers": false only sees the MCP tools listed for it under its own context_servers entry. Switch to a profile that includes the server, or add its tools to yours.
• When a server's tool list changes, Zed reloads it when the server sends notifications/tools/list_changed, with no restart. A server that doesn't send it shows its new tools after you restart Zed.
• Zed supports MCP tools and prompts. A server whose features are resources only adds nothing the agent can call.

Tool calls that wait or fail

• Every tool call asks for confirmation by default. Since Zed 0.224.0, agent.tool_permissions.default takes "confirm", "allow" or "deny", and a per-tool rule uses the key mcp:<server>:<tool_name>, for example mcp:github:create_issue. Older versions had one switch, agent.always_allow_tool_actions.
• A call the server rejects shows the server's own error message in the agent's reply. Read it there first: it usually names the missing key or argument.

Claude Code, Codex and other agents inside Zed

context_servers is for Zed's own agent. Command-line agents run in a terminal thread read their own MCP config, and external agents connected over ACP can get the servers Zed forwards or read their own native config. If Claude Code or Gemini CLI in Zed lacks a server, fix it in that agent's config: see Claude Code MCP server not connecting and Gemini CLI MCP server not loading.

Taskhold-specific checks

Taskhold is a remote server at https://taskhold.com/api/mcp. When its tools don't show up in Zed, check these in order:

1. The entry is under context_servers with url set to exactly https://taskhold.com/api/mcp and no headers. Zed then asks you to authenticate and finishes in your browser, with no sign-up first: the first time the agent uses Taskhold it gives you the link to start the 7-day trial.
2. If you added an Authorization header with an atd_sk_ key, Zed skips sign-in and sends the key. Taskhold's 401 names the cause: missing_key, bad_header, not_a_taskhold_key or unknown_key.
3. The dot is green but the agent says it has no taskhold tools: check the chat's profile includes the server.
4. Ask the agent to call the taskhold list tool. Settings in Taskhold shows the connection once the first call arrives.

With the tools loaded and the workflow from the Zed page in your rules file, every task Zed's agent starts, its steps and its questions show on the live board next to your other agents. The same checks for other clients: Cursor, Cline and Claude Desktop.