# 添加服务器 (/zh/docs/mcp-servers/adding-servers)

MCP 服务器要么可通过 HTTP 访问，要么是 Echolot 在你的 Mac 上启动并通过 stdio 与之通信的程序。你可以自己输入一个，也可以导入其他 App 已经知道的服务器。

## 添加服务器 [#adding-a-server]

在边栏的**服务器**标题处点按 **+**，选取**添加 MCP 服务器…** 在空的“MCP 服务器”页面上，**添加 MCP 服务器…** 按钮作用相同。

<Shot id="mcp-add-server" alt="GitHub 服务器的“添加 MCP 服务器”表单，“传输方式”菜单已展开：本地命令（stdio）或 HTTP（Streamable HTTP）；下方是参数、可选的工作目录和“环境”部分" />

为服务器指定一个**名称**，选取**传输方式**，填写下面的字段，然后点按**添加**。Echolot 会存储该服务器、选中它并检查它。服务器标题区中的**编辑…**（或它的右键菜单）会打开同一个表单；
**存储**会保留更改并再次检查服务器。可以用**编辑 › 撤销**撤销编辑。

### 通过 HTTP [#over-http]

选取 **HTTP（Streamable HTTP）**。

| 字段 | 填什么 |
| --- | --- |
| **URL** | 服务器的端点，例如 `https://demo.echolot.dev/mcp`。MCP 端点常常以 `/mcp` 结尾。 |
| **标头** | 随每条消息发送的标头，例如 `Authorization`，值为 `Bearer {{token}}`。点按**添加**可添加一行；复选框可以关闭某一行而不删除它。 |
| **OAuth** | 仅用于使用 OAuth 登录、且其授权服务器无法自行注册 Echolot 的服务器。参见[使用 OAuth 登录](#signing-in-with-oauth)。 |

仍然使用较旧的 HTTP+SSE 传输的服务器不需要单独的设置：在这里输入它们的 URL 即可，Streamable HTTP 被拒绝时，Echolot 会回退到 HTTP+SSE。以 `/sse` 结尾的 URL 会先尝试 HTTP+SSE。

### 作为本地命令（stdio） [#as-a-local-command-stdio]

选取**本地命令（stdio）**。

| 字段 | 填什么 |
| --- | --- |
| **命令** | 要启动的程序，例如 `npx`、`uvx`、`node` 或二进制文件的完整路径。 |
| **参数** | 它的参数，用空格分隔，例如 `-y @modelcontextprotocol/server-everything`。含有空格的参数请放在双引号中。 |
| **工作目录** | 程序启动的位置。可选。 |
| **环境** | 程序的环境变量，例如 `GITHUB_TOKEN`，值为 `{{github_token}}`。 |

Echolot 使用你的登录 shell 所具有的 `PATH` 启动程序，所以即使你是从访达或 Dock 打开 Echolot 的，`npx`、`uvx` 以及用 Homebrew、nvm、mise 或 Volta 安装的工具也能找到。
如果检查显示**服务器已启动**这一步失败，它会建议检查该命令是否已安装并在 `PATH` 上，或者给出它的完整路径。程序的错误输出显示在**消息**卡片中。

<Edition only="direct">
  本地（stdio）服务器在直接下载版中运行。App Store 版无法启动程序：它会把服务器保留在工作区中，并在原处显示**作为本地程序运行**。直接下载版和 `echolot` 命令行工具可以运行它。
  通过 HTTP 的 MCP 服务器在两个版本中都能使用。
</Edition>

## 运行前请审查 [#review-before-running]

来自工作区文件（比如同事的提交）或来自导入的本地服务器，还没有在这台 Mac 上启动过。Echolot 会显示**运行前请审查**，列出确切的**命令**、**参数**、**工作目录**和环境，
在你点按**信任并检查**之前不会启动任何内容。

你的批准属于这台 Mac 上这条确切的命令，绝不会写入工作区。如果命令、它的参数或它的环境发生变化，Echolot 会再次询问。你自己添加或编辑的服务器视为已批准，因为它们是你写的。

## 值和机密 [#values-and-secrets]

每个字段都可以使用 `{{variables}}`，在 Echolot 连接时根据活动[环境](/docs/workspaces/environments)解析。请把令牌和密钥保存在[机密变量](/docs/workspaces/secrets)中，并按名称引用它们：
`Bearer {{token}}`、`{{github_token}}`。机密值保留在钥匙串中，绝不会写入工作区，所以服务器的文件可以放心提交。

## 从其他 App 导入服务器 [#importing-servers-from-other-apps]

Echolot 读取 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf 和 Codex 的 MCP 服务器列表。

<Edition only="direct">
  直接下载版会自行找到这些文件。找到后，边栏底部的**在这台 Mac 上找到**框会列出每个 App，并带有**导入**按钮。**+** 菜单也在**导入自**下列出它们，
  而**选择配置文件…** 可以选取任何其他文件。用框上的 **×** 关闭它；导入仍可通过 **+** 菜单进行。
</Edition>

<Edition only="appstore">
  App Store 版无法自行读取其他 App 的文件。在 **+** › **导入自**下，选取该 App（例如 **Cursor…**）：打开面板会从该 App 的文件夹开始，由你选取文件。**选择配置文件…** 可以选取任何其他文件。
</Edition>

| App | 文件 |
| --- | --- |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Claude Code | `~/.claude.json`，或某个项目的 `.mcp.json` |
| Cursor | `~/.cursor/mcp.json` |
| VS Code | `~/Library/Application Support/Code/User/mcp.json`，或某个项目的 `.vscode/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Codex | `~/.codex/config.toml` |

你也可以将这些文件之一拖到窗口上，或在**文件 › 导入…** 中选取它：Echolot 会像识别其他[导入](/docs/get-started/importing)一样识别 MCP 客户端配置。

导入会做什么：

- 文件中的每个服务器都会成为工作区的一个服务器，与原来一样是本地的或 HTTP 的。
- 字面上的机密（`Authorization` 标头中的令牌、看起来像机密的环境变量中的密钥）会被移入工作区的机密变量，服务器按名称引用它们。导入报告会指出这些变量，绝不会给出值。
- 占位符会变成 Echolot 的值：`${env:NAME}` 和 `${NAME}` 在 Echolot 连接时读取环境变量 `NAME`，VS Code 的 `${input:id}` 会变成变量 `{{id}}`。报告会说明要添加哪些变量。
- Codex 的 `bearer_token_env_var` 会变成一个读取该环境变量的 `Authorization: Bearer` 标头。
- 原来已关闭的服务器会被导入，并在报告中附带一条备注。既没有命令也没有 URL 的服务器会被跳过。
- 导入的本地服务器会在[运行前请审查](#review-before-running)中等你处理。

## 使用 OAuth 登录 [#signing-in-with-oauth]

当服务器回应说它需要 OAuth 时，Echolot 会在页面顶部显示**需要登录**，其中有**授权服务器**以及 Echolot 如何获得客户端：

| **客户端**显示 | 含义 |
| --- | --- |
| **Echolot 自行注册** | 授权服务器自己接受新客户端。无需设置。 |
| **来自服务器的 OAuth 设置** | 你在服务器的 **OAuth** 部分输入了客户端 ID。 |
| **需要客户端 ID（编辑…）** | 授权服务器不注册客户端。请在那里注册一个，然后在**编辑…** › **OAuth** 下输入。 |

点按**登录…** Echolot 会打开你的浏览器，等待登录结果返回到 `127.0.0.1`，然后再次检查服务器。令牌会存入钥匙串，绝不会进入工作区。随后卡片会显示**已登录**，
以及授权服务器、范围、令牌的过期时间，如果是 Echolot 自行注册的，还会显示**由 Echolot 注册**。已过期但可以刷新的令牌会在下一次调用时刷新。

**退出登录**会忘记令牌以及 Echolot 注册的客户端。令牌本身在服务器上仍然有效，直到它过期。

服务器表单的 **OAuth** 部分用于自动发现无法处理的情况：

| 字段 | 留空时的默认行为 |
| --- | --- |
| **客户端 ID** | 自动注册。 |
| **客户端密钥** | 无。请使用机密变量，例如 `{{client_secret}}`。 |
| **范围** | 按服务器的要求。 |
| **重定向 URI** | `http://127.0.0.1:<any port>/callback`。 |

将该部分留空，则一切都自动发现。**标头**中的 `Authorization` 标头优先于 OAuth。

命令行工具用 `echolot mcp sign-in` 登录：在 Mac 上与 App 共用同一个钥匙串项目，或者为 CI 将登录信息打印为机密。参见 [echolot mcp](/docs/cli/mcp)。

## 检查失败时 [#when-a-check-fails]

**连接问题**卡片会指出失败的步骤，并给出修复建议：

| 步骤 | 常见原因 |
| --- | --- |
| **服务器已启动** | 命令没有安装或不在 `PATH` 上。在“终端”中运行它，看它为什么停止；它的错误输出在**消息**中。 |
| **服务器可访问** | 该主机和端口上没有任何监听，或 URL 的路径有误（MCP 端点常常是 `/mcp`）。 |
| **授权** | 没有人登录、凭据不被允许，或服务器需要 `Authorization` 标头。 |
| **存活检测** | 服务器没有应答 `ping`。它可能很忙，或不符合规范。 |
| **工具** | 一个或多个工具定义无效；该步骤会指出它们。 |