跳到主要内容

添加自定义 MCP Server

先从 Server 提供方取得官方配置，并确认其传输方式。不要根据包名、博客片段或未知仓库猜测启动命令和权限。

选择 Plugins → 连接管理 → 添加 Server。

Ghast 添加 MCP Server 对话框的 Stdio 表单和 Remote 标签
截图显示 Stdio 表单；切换到 Remote 标签后可填写 URL、协议、Headers 和 OAuth。

从剪贴板导入​

如果提供方给出 JSON 配置，先复制完整 JSON，再选择从剪贴板。Ghast 可以读取：

  • 包含 mcpServers 的配置，并导入其中第一个 Server；
  • 直接包含 command 的 stdio 配置；
  • 直接包含 url 的远程配置。

导入后不要立即保存。逐项核对名称、命令、参数、环境变量、URL、Headers 和 Remote Transport。剪贴板导入目前不会保留远程配置中的 SSE/transport 字段，远程项会回到默认的 Streamable HTTP；SSE Server 必须手动改回 SSE。无效 JSON 会显示剪贴板格式错误。

示例：

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"],
      "env": {
        "EXAMPLE_TOKEN": "replace-me"
      }
    }
  }
}

基本信息​

  • Server 名称：必填；会出现在连接管理和 Tool 分组中。使用可区分账号或环境的名称，例如 notion-work，不要只写 server。 同名配置会使后续排查困难。测试、预发布和生产 Server 应使用不同名称。

添加本地 stdio Server​

选择 Stdio，填写：

  • 命令：必填，要启动的可执行命令；
  • 参数：按空白分隔的参数；
  • 环境变量：每行一个 KEY=value。

示例：

命令
npx
参数
-y @modelcontextprotocol/server-filesystem /path/to/allowed-folder
环境变量
API_TOKEN=replace-me
LOG_LEVEL=warn

重要边界：

  • 命令以当前用户身份在本机运行；
  • Server 可以读取它被操作系统和参数允许访问的内容；
  • 环境变量会提供给 Server 进程；
  • 参数输入按空白拆分，不适合依赖复杂 Shell 引号；
  • 首次使用未知包管理命令可能联网下载和执行代码。

优先使用提供方的固定版本和明确入口。环境变量输入区会明文显示并在编辑时重新展示现有值；不要在参数中粘贴私钥、恢复短语或长期主密钥，长期凭证优先使用 OAuth 或 Plugin 凭证库。

添加远程 Server​

选择 Remote，填写：

  • URL：必填，Server 的完整 MCP 端点；
  • Remote Transport：Streamable HTTP 或 SSE；
  • Headers：可选，每行一个 Header: value；
  • 需要 OAuth：Server 使用浏览器授权时启用。

Header 示例：

Authorization: Bearer replace-me
X-Workspace-ID: workspace_123

优先使用 HTTPS。添加前确认域名、证书、服务条款和数据处理范围。Headers 输入区会明文显示并在编辑时重新展示现有值；这些 Header 会随 MCP 请求发送给该 URL，不要把同一 Token 复用到无关服务。

使用 OAuth​

  1. 输入完整远程 URL。
  2. 开启需要 OAuth。
  3. 选择授权。
  4. 在浏览器中核对域名、账号和 Scope。
  5. 完成授权并返回 Ghast。
  6. 确认界面显示已授权，再添加 Server。

界面在改变 URL 或 OAuth 开关后会清除“已授权”显示，但这不等于删除本机 Token 或撤销远端 Grant。当前自定义 Server 卡片和编辑框没有“断开/撤销 OAuth”按钮；编辑已经保存的 OAuth Server 前，请先到服务商的账号安全页面撤销旧授权，再修改 URL 或名称并重新授权。重命名也不会自动清理旧名称关联的本机 Token。授权失败时保留具体错误；不要退回到长期 Token，除非服务方明确支持且你理解其权限范围。

保存并验收​

选择添加后，按以下顺序验收：

  1. Server 卡片出现；
  2. 状态从连接中变为已连接；
  3. 没有“失败连接”或“受限连接”诊断；
  4. 连接诊断对应正确 Server，且没有能力发现错误；
  5. Resources 数量符合预期；
  6. 在新 Chat 中明确指定该服务，运行小范围只读请求；
  7. 核对返回的账号、项目和数据；
  8. 只有确实需要且明确授权时才测试写入；只读连接无需写入测试。

不要把“卡片出现”或“已连接”当成完整验收。

常见失败​

本地 Server 立即退出​

检查命令是否存在、参数是否被空白错误拆分、运行时是否安装、固定版本是否可下载，以及必需环境变量是否填写。

远程 Server 返回 401 或需要凭证​

检查 OAuth 是否完成、Header 名称和前缀是否正确、Token 是否属于当前环境，以及服务方是否要求预注册 OAuth 应用。

URL 可访问但无法握手​

确认端点是真正的 MCP 地址，并选择了正确的 Streamable HTTP 或 SSE。普通 REST API URL 不能直接当作 MCP Server。

已连接但没有 Tools​

Server 可能只公布 Resources，也可能能力发现失败。查看诊断，重新连接，并用提供方客户端确认 Server 实际公布的能力。