---
title: "MCP 服务器 - 让 AI 智能体给您发通知或打电话"
sidebarTitle: MCP 服务器
description: "将 Claude Code、Codex、Cursor、VS Code、ChatGPT 等 AI 智能体连接到 Echobell 官方 MCP 服务器，让它们向您发送推送通知或来电提醒。"
---

# 面向 AI 智能体的 MCP 服务器

Echobell 提供官方的 [Model Context Protocol](https://modelcontextprotocol.io)（MCP）服务器。把它连接到您的 AI 智能体——Claude Code、Codex、Cursor、VS Code、Windsurf、Gemini CLI、Claude、ChatGPT 或其他任何 MCP 客户端——智能体就会获得一个工具 `notify`，可以通过您的某个 Echobell 频道发送通知。

开始一次大型重构、一轮测试或一次部署，然后放心离开，让智能体在完成时告诉您。工作结束时手机会响起提醒；智能体需要您时会收到时效性通知；出现严重问题时，手机会像来电一样响铃。

## 工作原理

- 这是一个位于 `https://mcp.echobell.one/mcp` 的**远程** MCP 服务器，使用 Streamable HTTP 传输。无需安装任何东西：没有 npm 包，没有 `npx`，也没有本地进程。
- 每个 MCP URL 对应**一个频道**。智能体调用 `notify` 时，订阅该频道的每个人都会收到通知，并按各自选择的[通知类型](/docs/notification)送达。
- 凭据是频道的**触发令牌**——也就是频道 webhook URL 末尾的那个令牌。MCP 服务器的作用和频道的 [webhook](/docs/webhook) 一样，只是换成了智能体懂得如何调用的工具。

<Callout type="info">
  建议为智能体单独创建一个频道，例如“AI Agents”，并以**来电**类型订阅。这样智能体可以选择最高到来电的任意级别，您也可以把频道分享给想收到同样提醒的队友。
</Callout>

## 获取 MCP URL

### 从 App 获取

1. 打开 Echobell App，点击您想让智能体使用的频道。
2. 在频道详情中找到 **连接 AI 智能体**部分。
3. 复制 **MCP 服务器地址**，或复制适用于您的智能体的现成配置片段。

### 从 Webhook URL 推导

MCP URL 与频道的 webhook URL 使用同一个令牌。取出 webhook URL 末尾的令牌，接在 `https://mcp.echobell.one/mcp/` 后面即可：

```
Webhook URL: https://hook.echobell.one/t/<channel-token>
MCP URL:     https://mcp.echobell.one/mcp/<channel-token>
```

<Callout type="warn">
  MCP URL 中包含频道的触发令牌。任何拿到它的人都能向频道的订阅者发送通知，所以请像对待密码一样妥善保管。参见[安全](#安全)。
</Callout>

## 配置您的智能体

下面的配置片段都使用 URL 形式。请把 `<channel-token>` 替换为频道的触发令牌，或者直接粘贴 App 提供的片段，里面已经填好了令牌。

### Claude Code

```bash
claude mcp add --transport http echobell https://mcp.echobell.one/mcp/<channel-token>
```

加上 `--scope user` 可以让该服务器在所有项目中可用，而不只是当前项目。

### Codex

将以下内容添加到 `~/.codex/config.toml`：

```toml
[mcp_servers.echobell]
url = "https://mcp.echobell.one/mcp/<channel-token>"
```

### Cursor

将以下内容添加到 `~/.cursor/mcp.json`，或项目中的 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "echobell": {
      "url": "https://mcp.echobell.one/mcp/<channel-token>"
    }
  }
}
```

### VS Code（GitHub Copilot）

将以下内容添加到工作区的 `.vscode/mcp.json`，然后在 Copilot Chat 的智能体（agent）模式中使用该工具：

```json
{
  "servers": {
    "echobell": {
      "type": "http",
      "url": "https://mcp.echobell.one/mcp/<channel-token>"
    }
  }
}
```

如果 `.vscode/mcp.json` 会提交到代码仓库，请改用[带输入提示的请求头形式](#请求头形式)，让令牌不出现在文件里。

### Windsurf

将以下内容添加到 `~/.codeium/windsurf/mcp_config.json`：

```json
{
  "mcpServers": {
    "echobell": {
      "serverUrl": "https://mcp.echobell.one/mcp/<channel-token>"
    }
  }
}
```

### Gemini CLI

将以下内容添加到 `~/.gemini/settings.json`：

```json
{
  "mcpServers": {
    "echobell": {
      "httpUrl": "https://mcp.echobell.one/mcp/<channel-token>"
    }
  }
}
```

### Claude 桌面版和 claude.ai

1. 打开 **Settings → Connectors**。
2. 选择 **Add custom connector**。
3. 名称填写 `Echobell`，URL 填写 `https://mcp.echobell.one/mcp/<channel-token>`，然后添加。

该连接器在网页版 Claude 和桌面 App 中都可以使用。

### ChatGPT

1. 在 ChatGPT 设置中开启开发者模式（developer mode）。
2. 打开 **Settings → Connectors**，选择 **Create**。
3. 填入 URL `https://mcp.echobell.one/mcp/<channel-token>`，认证方式选择 **No authentication**——URL 中的令牌就是凭据。

### 其他 MCP 客户端

任何支持 Streamable HTTP 传输的客户端都可以使用。为它填入 URL `https://mcp.echobell.one/mcp/<channel-token>`，或使用下面的请求头形式。

### 请求头形式

除了把令牌放在 URL 中，您也可以通过 `Authorization` 请求头发送它。两种形式完全等效。

```
URL:            https://mcp.echobell.one/mcp
Authorization:  Bearer <channel-token>
```

在 Claude Code 中：

```bash
claude mcp add --transport http echobell https://mcp.echobell.one/mcp \
  --header "Authorization: Bearer <channel-token>"
```

在 VS Code 中，使用输入提示可以让令牌不出现在 `.vscode/mcp.json` 里，这样文件就可以放心提交。服务器第一次启动时，VS Code 会要求您输入令牌，并安全地保存它：

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "echobell-token",
      "description": "Echobell channel trigger token",
      "password": true
    }
  ],
  "servers": {
    "echobell": {
      "type": "http",
      "url": "https://mcp.echobell.one/mcp",
      "headers": {
        "Authorization": "Bearer ${input:echobell-token}"
      }
    }
  }
}
```

## `notify` 工具

服务器只提供一个工具：`notify`。智能体会根据您的提示词决定如何填写参数。

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `title` | string | 是 | 通知标题。 |
| `body` | string | 否 | 通知正文。 |
| `link` | string (URL) | 否 | 点击通知时打开的链接，例如拉取请求、构建日志或仪表盘。 |
| `urgency` | string | 否 | `normal`、`time-sensitive` 或 `calling`。省略时使用每位订阅者自己的级别。参见[紧急程度](#紧急程度)。 |

## 紧急程度

每位订阅频道的人都会在 App 中为它选择一种通知类型：普通、时效性或来电。这个选择是频道能提醒他的**最高**级别。

- 智能体省略 `urgency` 时，每位订阅者按自己选择的级别接收通知。
- 智能体发送 `urgency` 时，只能**降低**订阅者的级别，不能提高。如果您以来电类型订阅，`"urgency": "normal"` 会以普通通知送达；如果您以普通类型订阅，`"urgency": "calling"` 仍然以普通通知送达。

这样一个频道就能覆盖所有情况。以来电类型订阅，然后告诉智能体：日常进展用 `normal` 发送，只有出问题时才用 `calling`。

与 webhook 请求中的 `notificationType` 不同，`urgency` 在开启了自定义模板的频道上同样有效。

### 来电需要 Echobell 高级版

来电通知是 Echobell 高级版的功能。智能体请求 `calling` 时，没有高级版的订阅者会改为收到**时效性**通知——与 App 和 webhook 的行为相同。

### 每个频道每分钟最多来电一次

一个频道每分钟最多给每位订阅者打一次电话。如果智能体在这一分钟内再次请求来电（例如因为卡在不断重试中），订阅者会改为收到**时效性**通知，它仍然可以突破专注模式。Webhook 和电子邮件触发器也遵循同样的规则。

这两种情况智能体都会知道。工具结果会列出每一次降级，因此智能体知道手机并没有响铃，可以如实告诉您，而不是以为已经给您打过电话。

## 智能体收到的结果

每次调用 `notify` 都会返回一段给智能体看的简短文字摘要，以及结构化数据：

```json
{
  "notificationTriggered": true,
  "reason": null,
  "requestedUrgency": "calling",
  "recipients": 1,
  "deliveredUrgency": { "normal": 0, "time-sensitive": 1, "calling": 0 },
  "fallbacks": [
    {
      "from": "calling",
      "to": "time-sensitive",
      "reason": "premium-required",
      "recipients": 1
    }
  ]
}
```

| 字段 | 含义 |
|---|---|
| `notificationTriggered` | 已发送通知时为 `true`。 |
| `reason` | 未发送通知的原因：`conditions-not-met`（频道的[条件](/docs/conditions)不满足）或 `no-subscribers`（频道没有订阅者）。已发送通知时为 `null`。 |
| `requestedUrgency` | 智能体请求的 `urgency`；省略时为 `null`。 |
| `recipients` | 收到通知的订阅者人数。 |
| `deliveredUrgency` | 每个级别各有多少订阅者收到。 |
| `fallbacks` | 收到的级别低于请求级别的订阅者及原因：`premium-required`（来电需要高级版）、`subscriber-setting`（订阅者自己为频道设置的级别更低）或 `call-cooldown`（该频道在过去一分钟内已经给这位订阅者打过电话）。 |

## 直通频道和模板频道

MCP 服务器支持两种频道：

- **直通频道**（默认）按智能体发送的原样显示 `title` 和 `body`。
- **模板频道**（在**高级设置**中开启了**自定义模板**）根据您的[模板](/docs/template)生成通知。`title`、`body`、`link`、`externalLink` 和 `urgency` 都可以作为模板变量使用，频道的[条件](/docs/conditions)也照常生效。条件不满足时不会发送通知，智能体会收到 `reason: "conditions-not-met"`。

## 提示词示例

连接服务器后，用日常语言提出通知要求即可：

- “运行完整的测试套件，完成后用 Echobell 通知我。”
- “重构支付模块。如果需要我做决定，就给我发一条 Echobell 时效性提醒。”
- “部署到预发布环境。部署失败就给我打电话，否则发一条带 URL 的普通通知。”
- “迁移完成后通知我，附上摘要和拉取请求的链接。”

想让它成为习惯，可以在智能体的指令文件（`CLAUDE.md`、`AGENTS.md`、`.cursorrules` 等）中加上类似这样的内容：

```
When a task takes longer than a few minutes, call the Echobell notify tool when it finishes.
Use urgency "calling" only when something is broken and needs me right away.
```

## 安全

- **令牌就是凭据。** 任何拥有 MCP URL（或令牌）的人都能向频道的订阅者发送通知。它无法读取任何内容，也无法修改您的账户——唯一能做的就是发送通知。
- **不要放进共享文件。** 不要提交包含 URL 形式的配置文件。项目级配置请使用带输入提示或环境变量的[请求头形式](#请求头形式)。
- **重置触发令牌即可撤销访问。** 在 App 中打开频道并重置它的触发令牌。旧的 MCP URL 会立即失效（请求返回 `401 Unauthorized`），旧的 webhook URL 也一样。之后请用新令牌更新您的智能体和 webhook 调用方。

## 限制与错误

- **频率限制**：每个令牌每分钟最多接受 120 个 MCP 请求。MCP 请求有独立的额度，与频道的 webhook 请求分开计算。
- **401 Unauthorized**：令牌缺失、错误或已被重置。

## 相关内容

- [Webhook](/docs/webhook)——从脚本、CI 和其他服务触发同一个频道
- [通知类型](/docs/notification)——普通、时效性和来电有什么不同
- [模板](/docs/template)和[条件](/docs/conditions)——定制和筛选通知