Zed 中 MCP 服务器实战指南：安装、配置、权限控制与源码实现解析

Zed 通过 Model Context Protocol（MCP）将 AI Agent 与外部工具、数据源和集成连接起来，使 Zed Agent 能够调用 GitHub、数据库、Figma 等第三方能力。本文基于 Zed 官方文档（docs/src/ai/mcp.md）与仓库中 context_server 等核心 crate 的源码实现，完整讲解 MCP 服务器在 Zed 中的安装方式、context_servers 配置项细节、工具权限控制、Agent 工作路径差异，以及 Zed 作为 MCP 客户端在协议层（JSON-RPC 2.0、stdio/HTTP 传输、OAuth 认证、工具热重载）上的实际实现原理，帮助你从"会配置"深入到"懂原理"。

一、Zed 对 MCP 的支持范围

Zed 使用 Model Context Protocol 与 context server（MCP 服务器）交互。MCP 是一个开放协议，用于通过标准接口将 LLM 应用连接到外部工具和数据来源。

从源码 crates/context_server/src/types.rs 可以看到 Zed 客户端对协议版本的支持情况：

pub const VERSION_2024_11_05: &str = "2024-11-05";
pub const VERSION_2025_03_26: &str = "2025-03-26";
pub const VERSION_2025_06_18: &str = "2025-06-18";
pub const LATEST_PROTOCOL_VERSION: &str = "2025-11-25";

即 Zed 客户端声明支持的最新协议版本为 2025-11-25，并与服务器协商兼容的旧版本。当前 Zed 支持的 MCP 功能为：

• Tools（工具）：Agent 可在对话中调用的可执行工具，这是 MCP 在 Zed 中最核心的能力；
• Prompts（提示词）：MCP 服务器提供的提示模板；
• notifications/tools/list_changed 通知：当服务器在运行时增删或修改工具时，Zed 会收到该通知并自动重新加载工具列表，无需重启服务器。该通知在 types.rs 中定义：

notification!("notifications/tools/list_changed", ToolsListChanged, ());

此外，Zed 社区欢迎针对 Discovery、Sampling、Elicitation 等其余 MCP 特性的贡献。

底层请求与通知方法

types.rs 通过 request! / notification! 宏声明了 Zed 客户端实现的全部协议方法，包括 initialize、tools/list、tools/call、prompts/list、prompts/get、resources/*、completion/complete、ping、logging/setLevel、roots/list 等，以及 notifications/progress、notifications/cancelled、notifications/prompts/list_changed 等通知。可以看出 Zed 在协议类型层面对 MCP 规范做了完整映射，只是当前 Agent 能力主要消费其中 Tools 与 Prompts 两部分。

二、不同 Agent 路径下的 MCP 行为

Zed 中有多类 Agent 使用方式，MCP 服务器在不同路径下的行为各不相同：

Agent 路径	MCP 行为
Zed Agent	直接使用 Zed 中配置的 MCP 服务器
外部 Agent（External Agents）	Zed 可通过 ACP（Agent Client Protocol）将已配置的 MCP 服务器转发给外部 Agent；外部 Agent 也可以读取自己的原生 MCP 配置
Terminal Threads	原生 CLI/TUI 程序读取其自身的 MCP 配置，与 Zed 的 context_servers 配置无关

理解这张表很关键：在 Terminal Threads 中运行的 Claude Code、Codex 等 TUI 程序使用它们自己的 MCP 配置文件（如各自的 mcp.json），Zed 的 context_servers 设置不会传递过去；而 External Agents 则既可以接收 Zed 转发的 MCP 服务器，也可以使用自己原生配置中的 MCP 服务器。

三、安装 MCP 服务器

方式一：作为扩展（Extension）安装

MCP 服务器可以以扩展形式分发给 Zed 用户。你可以参考 MCP Server 扩展文档 学习如何创建自己的 MCP 服务器扩展。

在 Zed 中查找并安装 MCP 扩展的入口有三个：

1. Zed 官网的扩展页面（筛选 context-servers 类型）；
2. 应用内打开命令面板（Command Palette），执行 Extensions 动作（对应源码中的 zed::Extensions action）；
3. 应用内进入 Settings → AI → MCP Servers，点击 Add Server，选择 Install from Extensions。

以扩展形式提供的流行 MCP 服务器包括：Context7、GitHub、Puppeteer、Gem、Brave Search、Prisma、Framelink Figma、Resend 等。

从源码看，扩展引入的 context server 在设置中是 ContextServerSettingsContent 枚举的一个独立变体（见下文），带有 enabled、remote 和 settings 字段，其中 settings 是扩展自定义的 JSON 配置值。

方式二：作为自定义服务器配置

除扩展外，还可以在 Settings → AI → MCP Servers 页面（也可通过 agent::OpenSettings action 打开设置后选择 MCP Servers）点击 Add Server，选择 Add Local Server 或 Add Remote Server。配置向导会向你收集参数，并写入你的设置文件（可通过 zed::OpenSettingsFile action 打开），最终生成类似下面的 JSON：

{
  "context_servers": {
    "local-mcp-server": {
      "command": "some-command",
      "args": ["arg-1", "arg-2"],
      "env": {}
    },
    "remote-mcp-server": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    },
    "remote-mcp-server-with-oauth": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

注意：当远程 MCP 服务器没有配置 "Authorization" 请求头时，Zed 会引导你走标准的 MCP OAuth 流程对该服务器完成认证。

配置字段详解（结合源码）

上表配置项在源码中由 crates/settings_content/src/project.rs 的 ContextServerSettingsContent 枚举定义，它是 untagged 枚举，Zed 根据你提供的字段自动区分三种形态：

1. Stdio 本地服务器（含扩展服务器）：

Stdio {
    /// 是否启用该 context server，默认 true
    enabled: bool,
    /// 远程开发时是否在该远程服务器上运行此 context server；
    /// 默认 false，即始终在本地机器运行
    remote: bool,
    #[serde(flatten)]
    command: ContextServerCommand,  // 见下
},

其中 ContextServerCommand（project.rs）的字段为：

字段	说明
command	可执行文件路径（PathBuf）
args	命令行参数数组，默认空
env	环境变量映射，可选
timeout	工具调用超时时间（秒）。未指定时回退到全局 context_server_timeout，其默认值为 60 秒

一个值得注意的细节：ContextServerCommand 的 Debug 实现会对敏感环境变量（如 key、token 类名称）打印 [REDACTED]，避免日志泄露凭据（project.rs）。

2. Http 远程服务器：

Http {
    enabled: bool,          // 默认 true
    url: String,           // 远程 context server 的 URL
    headers: HashMap<String, String>,  // 可选的自定义请求头
    timeout: Option<u64>,  // 工具调用超时（秒），未指定时用全局 context_server_timeout
    oauth: Option<OAuthClientSettings>,
},

对于不支持动态客户端注册（Dynamic Client Registration）的授权服务器，可以预先通过 oauth 字段提供注册好的凭据（project.rs）：

字段	说明
client_id	与授权服务器进行带外（out-of-band）注册获得的 OAuth 客户端 ID
client_secret	机密客户端的 secret；出于安全考虑，Zed 会交互式提示输入并存入系统钥匙串（keychain），而非明文写入设置文件

3. Extension 扩展服务器：

Extension {
    enabled: bool,   // 默认 true
    remote: bool,   // 默认 false，远程开发时是否随服务器运行
    settings: serde_json::Value,  // 扩展声明的自定义设置
},

另外，全局的 context_server_timeout 定义在 crates/settings_content/src/project.rs，是所有服务器工具调用超时的兜底默认值（60 秒），且可被单个服务器的 timeout 覆盖。这与客户端实现中的默认请求超时相互呼应——crates/context_server/src/client.rs 中 DEFAULT_REQUEST_TIMEOUT 即为 60 秒。

四、验证 MCP 服务器是否配置成功

大多数 MCP 服务器安装后需要额外配置：

• 扩展：安装后 Zed 会弹出模态框，提示你还需要完成什么。例如 GitHub MCP 扩展要求你提供 GitHub 个人访问令牌（PAT）；
• 自定义服务器：请查阅服务器提供方文档，确认命令、参数和环境变量如何写入 JSON 配置。

验证方式：打开 Settings → AI → MCP Servers，观察服务器名称旁的指示圆点（indicator dot）：

• 绿色 + 提示文案 "Server is active"：服务器运行正常；
• 其他颜色和提示文案：表示启动失败、认证中、连接中或其他异常状态。

五、在 Agent 面板中使用 MCP 服务器

提示技巧

安装完成后回到 Agent 面板即可开始提问。不同模型调用 MCP 工具的可靠性有差异；在提示中明确提到 MCP 服务器的名称，有助于模型选中该服务器提供的工具。

用自定义 Profile 强制使用某个 MCP 服务器

如果你要确保某个 MCP 服务器被使用，可以创建一个自定义 Agent Profile，把所有内置工具（或可能与该服务器工具冲突的工具）关闭，只保留来自该 MCP 服务器的工具。

Dagger 团队就建议用这种方式搭配他们的 Container Use MCP 服务器，官方文档给出的完整配置示例如下：

{
  "agent": {
    "profiles": {
      "container-use": {
        "name": "Container Use",
        "tools": {
          "fetch": true,
          "copy_path": false,
          "find_path": false,
          "delete_path": false,
          "create_directory": false,
          "list_directory": false,
          "diagnostics": false,
          "read_file": false,
          "move_path": false,
          "grep": false,
          "edit_file": false,
          "terminal": false
        },
        "enable_all_context_servers": false,
        "context_servers": {
          "container-use": {
            "tools": {
              "environment_create": true,
              "environment_add_service": true,
              "environment_update": true,
              "environment_run_cmd": true,
              "environment_open": true,
              "environment_file_write": true,
              "environment_file_read": true,
              "environment_file_list": true,
              "environment_file_delete": true,
              "environment_checkpoint": true
            }
          }
        }
      }
    }
  }
}

这套 profile 配置的结构在源码 crates/settings_content/src/agent.rs 中有对应定义：AgentProfileContent 包含 name、tools（内置工具开关表）、enable_all_context_servers（是否默认启用所有 context server）、context_servers（按服务器名组织的 ContextServerPresetContent，其中 tools 为该服务器各工具的布尔开关表）以及 default_model（使用该 profile 时默认选择的语言模型）。

工具权限控制

注意： Zed v0.224.0 及以上版本中，工具审批由 agent.tool_permissions.default 控制；更早版本由布尔值 agent.always_allow_tool_actions 控制（默认 false）。

Zed Agent 面板提供 agent.tool_permissions.default 设置，用于控制原生 Zed Agent 的工具审批行为：

• "confirm"（默认）— 运行任何工具动作（包括 MCP 工具调用）前弹出审批提示；
• "allow" — 自动批准工具动作，不提示；
• "deny" — 阻断所有工具动作。

若要针对具体 MCP 工具做细粒度控制，可以配置按工具划分的权限规则。MCP 工具使用 mcp:<server>:<tool_name> 格式的键——例如 mcp:github:create_issue。由于 MCP 工具基于模式的规则匹配的是空字符串，大多数模式无法命中，因此按工具条目中的 default 键才是 MCP 工具权限的主要配置机制。更完整的权限体系说明见 工具权限文档。

六、External Agents 与 MCP 转发

在 Zed 中配置的 MCP 服务器会通过 Agent Client Protocol (ACP) 转发给外部 Agent。外部 Agent 同时也能访问它们自己原生配置文件里的 MCP 服务器。关于 Zed 与 External Agents 之间哪些配置相互共享、哪些相互隔离，参见 External Agents 文档的 Configuration Boundaries 一节。

七、错误处理与诊断

当 MCP 服务器在处理工具调用时发生错误，错误信息会直接传递给 Agent，本次工具操作随即失败。常见错误场景包括：

• 传给工具的参数不合法（invalid parameters）；
• 服务器端故障（数据库连接问题、触发限流等）；
• 不支持的操作或缺失的资源。

context server 返回的错误消息会展示在 Agent 的回复中，帮助你定位并修正问题；具体错误码请查阅对应 context server 的日志或文档。

协议层的错误码与超时机制

从源码看，crates/context_server/src/client.rs 定义了标准 JSON-RPC 错误码常量：

pub const PARSE_ERROR: i32 = -32700;
pub const INVALID_REQUEST: i32 = -32600;
pub const METHOD_NOT_FOUND: i32 = -32601;
pub const INVALID_PARAMS: i32 = -32602;
pub const INTERNAL_ERROR: i32 = -32603;

当你在 Agent 回复中遇到 "Invalid params" 一类错误时，对应的就是 -32602（INVALID_PARAMS），说明是参数构造问题而非服务器故障。

此外，客户端为每个请求维护 60 秒的默认超时（可被前述 timeout 配置覆盖）；Client 内部还通过单槽侧信道（last_transport_error）暂存最近一次传输层错误（如 "connection refused"），让下一个观察到的请求能以真实原因而非笼统的 "cancelled" 失败，便于诊断连接类问题（client.rs）。

八、context_server crate 源码结构速览

如果你想继续深入 Zed 的 MCP 客户端实现，可以从 crates/context_server 入手：

文件	职责
context_server.rs	ContextServer 入口，支持 Stdio（启动本地进程）与 Custom（自定义传输，如 HTTP）两种传输形态，执行 initialize 握手
client.rs	JSON-RPC 2.0 客户端：请求/通知分发、响应匹配、超时与取消处理
protocol.rs	在原始客户端之上的协议封装，如初始化后的上下文服务器协议
types.rs	协议版本常量、全部请求/通知方法的类型定义
transport/stdio_transport.rs	通过子进程 stdin/stdout 与本地 MCP 服务器通信
transport/http.rs	Streamable HTTP 传输；仅支持 http/https 协议（context_server.rs 中会对其他 URL scheme 报错），并对 2025-06-18 及以后版本实现 MCP-Protocol-Version 请求头要求
oauth.rs	MCP OAuth 认证流程（含 401 挑战解析、动态/预注册客户端）
listener.rs	监听服务器端请求（如 Roots 能力），使 Zed 可作为 MCP 客户端响应服务器的反向请求
test.rs	测试用的 mock 服务器支持

总结

• Zed 通过 context_servers 配置统一纳管本地（stdio）、远程（HTTP）与扩展形式三类 MCP 服务器，配置字段、超时与 OAuth 行为均可在 crates/settings_content/src/project.rs 中对照源码核实；
• 日常使用路径：扩展安装或 JSON 自定义配置 → 用指示圆点验证状态 → 在 Agent 面板提示中按名称点名服务器，必要时用 Agent Profile 锁定工具集；
• 安全与可控性由 agent.tool_permissions 体系保障，MCP 工具以 mcp:<server>:<tool_name> 键做按工具授权；
• Terminal Threads 与 External Agents 遵循不同的 MCP 配置边界，配置前请先确认你所在的 Agent 路径。