跳到主要内容

添加 MCP 服务器

本页介绍如何在 Elftia 中添加和配置 MCP 服务器。Elftia 支持三种传输类型,每种类型的配置方式略有不同。

打开 MCP 管理页面​

  1. 点击左侧导航栏的 MCP 服务器 页面
  2. 点击右上角的 添加 按钮
  3. 在弹出的表单中选择 表单输入 模式
提示

你也可以通过 JSON 导入 模式批量添加服务器,详见 JSON 批量导入。

添加 Stdio 服务器​

Stdio 是最常用的传输类型,适用于通过本地命令行启动的 MCP 服务器(如 npm 包、Python 包等)。

配置步骤​

  1. 服务器名称 — 输入一个易于识别的名称(如 filesystem)
  2. 传输类型 — 选择 Stdio
  3. 命令 — 输入启动服务器的命令(如 npx)
  4. 参数 — 每行一个参数:
    -y
    @modelcontextprotocol/server-filesystem
    /path/to/allowed/directory
  5. 环境变量(可选)— 每行一个,格式为 KEY=VALUE:
    API_KEY=your-api-key
    DEBUG=true
  6. 点击 保存

配置字段说明​

字段必填说明
服务器名称是唯一标识名,不可与已有服务器重名
命令是可执行命令,如 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 长连接通信。

配置步骤​

  1. 服务器名称 — 输入名称(如 web-search)
  2. 传输类型 — 选择 SSE
  3. URL — 输入服务器的 SSE 端点地址
  4. 请求头(可选)— 每行一个,格式为 Key=Value:
    Authorization=Bearer your-token
    X-API-Key=your-api-key
  5. 环境变量(可选)— 同 Stdio
  6. 点击 保存

配置字段说明​

字段必填说明
服务器名称是唯一标识名
URL是MCP 服务器的 SSE 端点 URL
请求头否HTTP 请求头,用于认证等
环境变量否额外环境变量

SSE 服务器示例​

智谱网络搜索:

字段值
URLhttps://api.z.ai/api/mcp/web_search_prime/mcp
请求头Authorization=Bearer your-zhipu-api-key

添加 HTTP 服务器​

HTTP 传输(Streamable HTTP)基于 MCP 2025-03-26 规范,是较新的传输方式。

配置步骤​

  1. 服务器名称 — 输入名称
  2. 传输类型 — 选择 HTTP
  3. URL — 输入服务器的 HTTP 端点地址
  4. 请求头(可选)— 同 SSE
  5. 点击 保存

配置字段说明​

与 SSE 相同,仅传输协议不同。

字段必填说明
服务器名称是唯一标识名
URL是MCP 服务器的 HTTP 端点 URL
请求头否HTTP 请求头
环境变量否额外环境变量

HTTP 服务器示例​

智谱网页阅读器:

字段值
URLhttps://api.z.ai/api/mcp/web_reader/mcp
请求头Authorization=Bearer your-zhipu-api-key

依赖检查​

添加 Stdio 服务器时,Elftia 会自动检查所需的命令行工具是否已安装:

命令检查内容自动安装方式
npx / npm / nodeNode.js 运行时Windows: winget; macOS: Homebrew; 其他: 提示手动安装
uv / uvxuv Python 包管理器通过官方安装脚本自动安装

如果检测到依赖缺失,Elftia 会弹出提示,提供自动安装或手动下载链接。

依赖检查行为​

  • 优先从系统 PATH 查找命令
  • 如未找到,自动扫描常见安装目录(~/.local/bin、~/.cargo/bin、npm 全局目录等)
  • 安装完成后自动验证是否可用
  • 对于无法自动安装的依赖,提供下载页面链接

测试连接​

添加服务器后,建议立即测试连接:

  1. 在 MCP 服务器列表中找到目标服务器
  2. 点击 测试 按钮
  3. 等待连接和工具发现完成
  4. 成功时会显示 Connected successfully. Found N tools. 以及工具名称列表

使用官方预设​

Elftia 内置了一些常用 MCP 服务器的预设配置,支持一键安装:

  1. 在 MCP 服务器页面切换到 官方 标签
  2. 浏览可用的预设列表(按类别筛选:搜索、视觉、网页阅读、代码仓库等)
  3. 点击 安装 按钮
  4. 如果需要 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 分钟过期,等待缓存刷新或重新连接

下一步​