添加 MCP 服务器
本页介绍如何在 Elftia 中添加和配置 MCP 服务器。Elftia 支持三种传输类型，每种类型的配置方式略有不同。
打开 MCP 管理页面
- 点击左侧导航栏的 MCP 服务器 页面
- 点击右上角的 添加 按钮
- 在弹出的表单中选择 表单输入 模式
tip
你也可以通过 JSON 导入 模式批量添加服务器，详见 JSON 批量导入。
添加 Stdio 服务器
Stdio 是最常用的传输类型，适用于通过本地命令行启动的 MCP 服务器（如 npm 包、Python 包等）。
配置步骤
- 服务器名称 — 输入一个易于识别的名称（如
filesystem） - 传输类型 — 选择
Stdio - 命令 — 输入启动服务器的命令（如
npx） - 参数 — 每行一个参数：
-y@modelcontextprotocol/server-filesystem/path/to/allowed/directory
- 环境变量（可选）— 每行一个，格式为
KEY=VALUE：API_KEY=your-api-keyDEBUG=true - 点击 保存
配置字段说明
| 字段 | 必填 | 说明 |
|---|---|---|
| 服务器名称 | 是 | 唯一标识名，不可与已有服务器重名 |
| 命令 | 是 | 可执行命令，如 npx、uvx、node、python |
| 参数 | 否 | 传递给命令的参数列表，每行一个 |
| 环境变量 | 否 | 子进程的额外环境变量，继承当前系统环境 |
常用 Stdio 服务器示例
文件系统服务器：
| 字段 | 值 |
|---|---|
| 命令 | npx |
| 参数 | -y , @modelcontextprotocol/server-filesystem , /Users/yourname/Documents |
Brave 搜索服务器：
| 字段 | 值 |
|---|---|
| 命令 | npx |
| 参数 | -y , @modelcontextprotocol/server-brave-search@latest |
| 环境变量 | BRAVE_API_KEY=your-brave-api-key |
Tavily 搜索服务器：
| 字段 | 值 |
|---|---|
| 命令 | npx |
| 参数 | -y , tavily-mcp@latest |
| 环境变量 | TAVILY_API_KEY=your-tavily-api-key |
添加 SSE 服务器
SSE（Server-Sent Events）适用于远程托管的 MCP 服务器，通过 HTTP 长连接通信。
配置步骤
- 服务器名称 — 输入名称（如
web-search） - 传输类型 — 选择
SSE - URL — 输入服务器的 SSE 端点地址
- 请求头（可选）— 每行一个，格式为
Key=Value：Authorization=Bearer your-tokenX-API-Key=your-api-key - 环境变量（可选）— 同 Stdio
- 点击 保存
配置字段说明
| 字段 | 必填 | 说明 |
|---|---|---|
| 服务器名称 | 是 | 唯一标识名 |
| URL | 是 | MCP 服务器的 SSE 端点 URL |
| 请求头 | 否 | HTTP 请求头，用于认证等 |
| 环境变量 | 否 | 额外环境变量 |
SSE 服务器示例
智谱网络搜索：
| 字段 | 值 |
|---|---|
| URL | https://api.z.ai/api/mcp/web_search_prime/mcp |
| 请求头 | Authorization=Bearer your-zhipu-api-key |
添加 HTTP 服务器
HTTP 传输（Streamable HTTP）基于 MCP 2025-03-26 规范，是较新的传输方式。
配置步骤
- 服务器名称 — 输入名称
- 传输类型 — 选择
HTTP - URL — 输入服务器的 HTTP 端点地址
- 请求头（可选）— 同 SSE
- 点击 保存
配置字段说明
与 SSE 相同，仅传输协议不同。
| 字段 | 必填 | 说明 |
|---|---|---|
| 服务器名称 | 是 | 唯一标识名 |
| URL | 是 | MCP 服务器的 HTTP 端点 URL |
| 请求头 | 否 | HTTP 请求头 |
| 环境变量 | 否 | 额外环境变量 |
HTTP 服务器示例
智谱网页阅读器：
| 字段 | 值 |
|---|---|
| URL | https://api.z.ai/api/mcp/web_reader/mcp |
| 请求头 | Authorization=Bearer your-zhipu-api-key |
依赖检查
添加 Stdio 服务器时，Elftia 会自动检查所需的命令行工具是否已安装：
| 命令 | 检查内容 | 自动安装方式 |
|---|---|---|
npx / npm / node | Node.js 运行时 | Windows: winget; macOS: Homebrew; 其他: 提示手动安装 |
uv / uvx | uv Python 包管理器 | 通过官方安装脚本自动安装 |
如果检测到依赖缺失，Elftia 会弹出提示，提供自动安装或手动下载链接。
依赖检查行为
- 优先从系统 PATH 查找命令
- 如未找到，自动扫描常见安装目录（
~/.local/bin、~/.cargo/bin、npm 全局目录等） - 安装完成后自动验证是否可用
- 对于无法自动安装的依赖，提供下载页面链接
测试连接
添加服务器后，建议立即测试连接：
- 在 MCP 服务器列表中找到目标服务器
- 点击 测试 按钮
- 等待连接和工具发现完成
- 成功时会显示
Connected successfully. Found N tools.以及工具名称列表
使用官方预设
Elftia 内置了一些常用 MCP 服务器的预设配置，支持一键安装：
- 在 MCP 服务器页面切换到 官方 标签
- 浏览可用的预设列表（按类别筛选：搜索、视觉、网页阅读、代码仓库等）
- 点击 安装 按钮
- 如果需要 API Key，系统会尝试从已配置的 LLM 提供商中自动关联；如未关联到，需手动输入
当前支持的官方预设包括：
| 预设 | 类别 | 传输 | 需要 API Key |
|---|---|---|---|
| MiniMax Coding Plan MCP | 通用 | Stdio | 是 |
| Zhipu Vision MCP | 视觉 | Stdio | 是 |
| Zhipu Web Search | 搜索 | HTTP | 是 |
| Zhipu Web Reader | 网页阅读 | HTTP | 是 |
| Zhipu Zread | 代码仓库 | HTTP | 是 |
| Tavily Search | 搜索 | Stdio | 是 |
| Brave Search | 搜索 | Stdio | 是 |
故障排除
命令未找到
症状：添加 Stdio 服务器时提示命令不存在。
解决方案：
- 确认相关运行时已安装（Node.js、Python 等）
- 尝试在终端中手动运行该命令验证
- 重启 Elftia 以刷新 PATH 环境变量
- 使用完整路径代替命令名（如
/usr/local/bin/npx）
连接超时
症状：测试连接时长时间无响应。
解决方案：
- 检查网络连接（对于 SSE/HTTP 服务器）
- 确认 URL 是否正确，特别是端口和路径
- 检查防火墙或代理设置是否阻止了连接
- 对于 Stdio 服务器，确认命令能正常启动
认证错误
症状：连接成功但工具调用失败，提示认证相关错误。
解决方案：
- 检查 API Key 是否正确设置在环境变量中
- 对于 SSE/HTTP 服务器，确认请求头中的认证信息格式正确
- 注意 Bearer Token 的格式：
Authorization=Bearer your-token
工具未显示
症状：服务器连接成功但对话中未出现工具。
解决方案：
- 确认服务器处于启用状态（
isActive为 true） - 检查 MCP 模式是否设为
disabled - 在手动模式下，确认已选择该服务器
- 尝试使用 发现 按钮手动刷新工具列表
- 工具缓存每 5 分钟过期，等待缓存刷新或重新连接