---
title: "Servidor MCP - Agentes de IA avisam ou ligam para você"
sidebarTitle: Servidor MCP
description: "Conecte Claude Code, Codex, Cursor, ChatGPT e outros agentes de IA ao servidor MCP oficial do Echobell para receber uma notificação push ou uma chamada."
---

# Servidor MCP para agentes de IA

O Echobell tem um servidor oficial de [Model Context Protocol](https://modelcontextprotocol.io) (MCP). Conecte-o ao seu agente de IA — Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude, ChatGPT ou qualquer outro cliente MCP — e o agente ganha uma ferramenta, `notify`, que envia uma notificação por um dos seus canais do Echobell.

Comece uma refatoração longa, uma rodada de testes ou um deploy, vá fazer outra coisa e peça ao agente para avisar quando terminar. Seu celular vibra quando o trabalho acaba, mostra um alerta urgente quando o agente precisa de você ou toca como uma chamada quando algo dá muito errado.

## Como funciona

- É um servidor MCP **remoto** em `https://mcp.echobell.one/mcp`, com o transporte Streamable HTTP. Não há nada para instalar: nenhum pacote npm, nenhum `npx`, nenhum processo local.
- Cada URL de MCP pertence a **um canal**. Quando o agente chama `notify`, todos os inscritos nesse canal recebem a notificação, cada um com o [tipo de notificação](/docs/notification) que escolheu.
- A credencial é o **token de gatilho** do canal — o mesmo token que fica no final da URL do webhook do canal. O servidor MCP funciona como o [webhook](/docs/webhook) do canal, só que com uma ferramenta que o agente sabe chamar.

<Callout type="info">
  Crie um canal dedicado aos seus agentes, por exemplo "AI Agents", e inscreva-se
  nele com o tipo **Chamada**. Assim seus agentes podem escolher qualquer nível
  até uma chamada, e você pode compartilhar o canal com colegas que queiram os
  mesmos alertas.
</Callout>

## Obtenha sua URL de MCP

### Pelo app

1. Abra o app Echobell e toque no canal que você quer que o agente use.
2. Nos detalhes do canal, encontre a seção **Conectar agente de IA**.
3. Copie a **URL do servidor MCP** ou o trecho de configuração pronto para o seu agente.

### Pela URL do webhook

A URL de MCP usa o mesmo token da URL do webhook do canal. Pegue o token do final da URL do webhook e coloque-o depois de `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">
  A URL de MCP contém o token de gatilho do seu canal. Qualquer pessoa que a
  tenha pode enviar notificações aos inscritos do canal, então guarde-a com o
  mesmo cuidado que uma senha. Veja [Segurança](#segurança).
</Callout>

## Configure seu agente

Todos os trechos abaixo usam o formato com URL. Substitua `<channel-token>` pelo token de gatilho do seu canal ou cole o trecho que o app fornece, que já vem preenchido.

### Claude Code

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

Adicione `--scope user` para deixar o servidor disponível em todos os projetos, e não só no atual.

### Codex

Adicione isto a `~/.codex/config.toml`:

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

### Cursor

Adicione isto a `~/.cursor/mcp.json`, ou a `.cursor/mcp.json` dentro de um projeto:

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

### VS Code (GitHub Copilot)

Adicione isto a `.vscode/mcp.json` no seu workspace e use a ferramenta no Copilot Chat em modo agente:

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

Se o `.vscode/mcp.json` for versionado no seu repositório, use o [formato com cabeçalho e um prompt de entrada](#formato-com-cabeçalho), para que o token fique fora do arquivo.

### Windsurf

Adicione isto a `~/.codeium/windsurf/mcp_config.json`:

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

### Gemini CLI

Adicione isto a `~/.gemini/settings.json`:

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

### Claude Desktop e claude.ai

1. Abra **Settings → Connectors**.
2. Escolha **Add custom connector**.
3. Informe o nome `Echobell` e a URL `https://mcp.echobell.one/mcp/<channel-token>` e adicione o conector.

O conector fica disponível no Claude na web e no app para desktop.

### ChatGPT

1. Ative o modo desenvolvedor nas configurações do ChatGPT.
2. Abra **Settings → Connectors** e escolha **Create**.
3. Informe a URL `https://mcp.echobell.one/mcp/<channel-token>` e defina a autenticação como **No authentication** — o token na URL é a credencial.

### Outros clientes MCP

Qualquer cliente compatível com o transporte Streamable HTTP funciona. Informe a URL `https://mcp.echobell.one/mcp/<channel-token>` ou use o formato com cabeçalho abaixo.

### Formato com cabeçalho

Em vez de colocar o token na URL, você pode enviá-lo em um cabeçalho `Authorization`. Os dois formatos são equivalentes.

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

Com o Claude Code:

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

No VS Code, um prompt de entrada (input) mantém o token fora do `.vscode/mcp.json`, então o arquivo pode ser versionado com segurança. O VS Code pede o token na primeira vez que o servidor inicia e o guarda de forma segura:

```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}"
      }
    }
  }
}
```

## A ferramenta `notify`

O servidor expõe uma única ferramenta, `notify`. O agente decide como preenchê-la a partir do seu prompt.

| Argumento | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `title` | string | Sim | Título da notificação. |
| `body` | string | Não | Corpo da notificação. |
| `link` | string (URL) | Não | Um link aberto quando você toca na notificação, como um pull request, o log de um build ou um dashboard. |
| `urgency` | string | Não | `normal`, `time-sensitive` ou `calling`. Omita para usar o nível de cada inscrito. Veja [Urgência](#urgência). |

## Urgência

Quem se inscreve em um canal escolhe um tipo de notificação para ele no app: Normal, Urgente ou Chamada. Essa escolha é o nível **mais alto** com que o canal pode alcançar essa pessoa.

- Quando o agente omite `urgency`, cada inscrito recebe o nível que escolheu.
- Quando o agente envia `urgency`, ele só pode **baixar** o nível de um inscrito, nunca aumentar. Se você se inscreveu com Chamada, `"urgency": "normal"` chega como uma notificação normal. Se você se inscreveu com Normal, `"urgency": "calling"` continua chegando como uma notificação normal.

Assim, um único canal dá conta de tudo. Inscreva-se com Chamada e peça ao agente para enviar atualizações de rotina como `normal` e usar `calling` só quando algo estiver quebrado.

Ao contrário de `notificationType` nas requisições de webhook, `urgency` também funciona em canais com template personalizado.

### Chamadas exigem o Echobell Premium

Notificações de chamada são um recurso do Echobell Premium. Quando o agente pede `calling`, um inscrito sem Premium recebe uma notificação **urgente** (time-sensitive) no lugar — o mesmo que acontece com o app e com os webhooks.

### Uma chamada por minuto em cada canal

Um canal liga para cada inscrito no máximo uma vez por minuto. Se o agente pedir outra chamada dentro desse minuto — por exemplo, porque ficou preso tentando de novo —, o inscrito recebe uma notificação **urgente** no lugar, que ainda atravessa os modos de foco. Webhooks e gatilhos por e-mail seguem a mesma regra.

O agente fica sabendo nos dois casos. O resultado da ferramenta lista cada rebaixamento de nível, então o agente sabe que o celular não tocou e pode dizer isso em vez de supor que ligou para você.

## O que o agente recebe de volta

Cada chamada a `notify` retorna um breve resumo em texto para o agente e dados estruturados:

```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
    }
  ]
}
```

| Campo | Significado |
|---|---|
| `notificationTriggered` | `true` quando uma notificação foi enviada. |
| `reason` | Por que nada foi enviado: `conditions-not-met` (as [condições](/docs/conditions) do canal não foram atendidas) ou `no-subscribers` (ninguém está inscrito no canal). `null` quando uma notificação foi enviada. |
| `requestedUrgency` | A `urgency` que o agente pediu, ou `null` quando ele a omitiu. |
| `recipients` | Quantos inscritos foram notificados. |
| `deliveredUrgency` | Quantos inscritos receberam cada nível. |
| `fallbacks` | Inscritos que receberam um nível mais baixo que o pedido, e por quê: `premium-required` (chamadas exigem Premium), `subscriber-setting` (o nível que o próprio inscrito escolheu para o canal é mais baixo) ou `call-cooldown` (o canal já ligou para esse inscrito no último minuto). |

## Canais de repasse direto e canais com modelo

O servidor MCP funciona com os dois tipos de canal:

- **Canais de repasse direto** (o padrão) mostram o `title` e o `body` exatamente como o agente envia.
- **Canais com modelo** (com **Modelo personalizado** ativado em **Configurações avançadas**) montam a notificação a partir dos seus [modelos](/docs/template). `title`, `body`, `link`, `externalLink` e `urgency` ficam disponíveis como variáveis de modelo, e as [condições](/docs/conditions) do canal continuam valendo. Quando as condições não são atendidas, nada é enviado e o agente recebe `reason: "conditions-not-met"`.

## Exemplos de prompts

Com o servidor conectado, peça notificações em linguagem natural:

- "Rode toda a suíte de testes e me avise pelo Echobell quando terminar."
- "Refatore o módulo de pagamentos. Me mande um alerta urgente do Echobell se precisar de uma decisão minha."
- "Faça o deploy em staging. Me ligue se o deploy falhar; senão, mande uma notificação normal com a URL."
- "Quando a migração terminar, me avise com um resumo e um link para o pull request."

Para virar hábito, adicione uma linha como esta ao arquivo de instruções do seu agente (`CLAUDE.md`, `AGENTS.md`, `.cursorrules` etc.):

```
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.
```

## Segurança

- **O token é a credencial.** Quem tiver a URL de MCP (ou o token) pode enviar notificações aos inscritos do canal. Não dá para ler nada nem alterar sua conta — a única coisa possível é notificar.
- **Mantenha-o fora de arquivos compartilhados.** Não versione um arquivo de configuração que contenha o formato com URL. Para configuração no nível do projeto, use o [formato com cabeçalho](#formato-com-cabeçalho) com um prompt de entrada ou uma variável de ambiente.
- **Revogue o acesso redefinindo o token de gatilho.** Abra o canal no app e redefina o token de gatilho. A URL de MCP antiga para de funcionar na hora (as requisições recebem `401 Unauthorized`), assim como a URL do webhook antiga. Atualize seus agentes e quem chama o webhook com o novo token.

## Limites e erros

- **Limite de taxa**: cada token aceita até 120 requisições MCP por minuto. As requisições MCP têm uma cota própria, separada das requisições ao webhook do canal.
- **401 Unauthorized**: o token está ausente, incorreto ou foi redefinido.

## Relacionados

- [Webhooks](/docs/webhook) — dispare o mesmo canal a partir de scripts, CI e outros serviços
- [Tipos de notificação](/docs/notification) — a diferença entre Normal, Urgente e Chamada
- [Modelos](/docs/template) e [Condições](/docs/conditions) — formate e filtre as notificações