---
title: "Server MCP - Fatti avvisare o chiamare dai tuoi agenti IA"
sidebarTitle: Server MCP
description: "Collega Claude Code, Codex, Cursor, ChatGPT e altri agenti IA al server MCP ufficiale di Echobell per ricevere una notifica push o una chiamata."
---

# Server MCP per agenti IA

Echobell gestisce un server ufficiale per il [Model Context Protocol](https://modelcontextprotocol.io) (MCP). Collegalo al tuo agente IA — Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude, ChatGPT o qualsiasi altro client MCP — e l'agente avrà a disposizione uno strumento, `notify`, che invia una notifica tramite uno dei tuoi canali Echobell.

Avvia un grosso refactoring, una suite di test o un deploy, allontanati e chiedi all'agente di avvisarti quando ha finito. Il telefono vibra quando il lavoro è concluso, mostra un avviso urgente quando l'agente ha bisogno di te, oppure squilla come una telefonata quando qualcosa va storto sul serio.

## Come funziona

- È un server MCP **remoto**, all'indirizzo `https://mcp.echobell.one/mcp`, che usa il trasporto Streamable HTTP. Non c'è niente da installare: nessun pacchetto npm, nessun `npx`, nessun processo locale.
- Ogni URL MCP appartiene a **un canale**. Quando l'agente chiama `notify`, tutti gli iscritti a quel canale ricevono la notifica, ciascuno con il [tipo di notifica](/docs/notification) che ha scelto.
- La credenziale è il **token del trigger** del canale, lo stesso token con cui termina l'URL webhook del canale. Il server MCP funziona come il [webhook](/docs/webhook) del canale, con in più uno strumento che l'agente sa come chiamare.

<Callout type="info">
  Crea un canale dedicato ai tuoi agenti, ad esempio "Agenti IA", e iscriviti
  con il tipo **Chiamata**. I tuoi agenti potranno così scegliere qualsiasi
  livello fino alla chiamata, e potrai condividere il canale con i colleghi che
  vogliono ricevere gli stessi avvisi.
</Callout>

## Ottieni il tuo URL MCP

### Dall'app

1. Apri l'app Echobell e tocca il canale che il tuo agente deve usare.
2. Nei dettagli del canale, trova la sezione **Collega un agente IA**.
3. Copia l'**URL del server MCP**, oppure lo snippet di configurazione già pronto per il tuo agente.

### Dall'URL del webhook

L'URL MCP usa lo stesso token dell'URL webhook del canale. Prendi il token dalla fine dell'URL webhook e mettilo dopo `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">
  L'URL MCP contiene il token del trigger del tuo canale. Chiunque lo possieda
  può inviare notifiche agli iscritti del canale, quindi custodiscilo come una
  password. Vedi [Sicurezza](#sicurezza).
</Callout>

## Configura il tuo agente

Tutti gli snippet qui sotto usano la forma con URL. Sostituisci `<channel-token>` con il token del trigger del tuo canale, oppure incolla lo snippet che ti dà l'app, dove è già inserito.

### Claude Code

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

Aggiungi `--scope user` per rendere il server disponibile in tutti i progetti, non solo in quello corrente.

### Codex

Aggiungi questo a `~/.codex/config.toml`:

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

### Cursor

Aggiungi questo a `~/.cursor/mcp.json`, oppure a `.cursor/mcp.json` all'interno di un progetto:

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

### VS Code (GitHub Copilot)

Aggiungi questo a `.vscode/mcp.json` nel tuo workspace, poi usa lo strumento da Copilot Chat in modalità agente:

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

Se `.vscode/mcp.json` è incluso nel tuo repository, usa invece la [forma con header e richiesta di input](#forma-con-header), così il token resta fuori dal file.

### Windsurf

Aggiungi questo a `~/.codeium/windsurf/mcp_config.json`:

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

### Gemini CLI

Aggiungi questo a `~/.gemini/settings.json`:

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

### Claude Desktop e claude.ai

1. Apri **Impostazioni → Connettori**.
2. Scegli **Aggiungi connettore personalizzato**.
3. Inserisci il nome `Echobell` e l'URL `https://mcp.echobell.one/mcp/<channel-token>`, poi aggiungilo.

Il connettore è disponibile in Claude sul web e nell'app desktop.

### ChatGPT

1. Attiva la modalità sviluppatore nelle impostazioni di ChatGPT.
2. Apri **Impostazioni → Connettori** e scegli **Crea**.
3. Inserisci l'URL `https://mcp.echobell.one/mcp/<channel-token>` e imposta l'autenticazione su **Nessuna autenticazione**: la credenziale è il token nell'URL.

### Altri client MCP

Funziona qualsiasi client che supporti il trasporto Streamable HTTP. Indica l'URL `https://mcp.echobell.one/mcp/<channel-token>`, oppure usa la forma con header descritta qui sotto.

### Forma con header

Invece di mettere il token nell'URL, puoi inviarlo in un header `Authorization`. Le due forme sono equivalenti.

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

Con Claude Code:

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

In VS Code, una richiesta di input tiene il token fuori da `.vscode/mcp.json`, così puoi includere il file nel repository senza rischi. VS Code chiede il token al primo avvio del server e lo conserva in modo sicuro:

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

## Lo strumento `notify`

Il server espone un solo strumento, `notify`. È il tuo agente a decidere come compilarlo in base al prompt.

| Argomento | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `title` | string | Sì | Titolo della notifica. |
| `body` | string | No | Testo della notifica. |
| `link` | string (URL) | No | Un link che si apre quando tocchi la notifica, ad esempio una pull request, un log di build o una dashboard. |
| `urgency` | string | No | `normal`, `time-sensitive` o `calling`. Omettilo per usare il livello scelto da ciascun iscritto. Vedi [Urgenza](#urgenza). |

## Urgenza

Chi si iscrive a un canale sceglie nell'app un tipo di notifica: Normale, Urgente o Chiamata. Quella scelta è il livello **più alto** con cui il canale può raggiungerlo.

- Quando l'agente omette `urgency`, ogni iscritto riceve il livello che ha scelto.
- Quando l'agente invia `urgency`, può solo **abbassare** il livello di un iscritto, mai alzarlo. Se sei iscritto con Chiamata, `"urgency": "normal"` arriva come notifica normale. Se sei iscritto con Normale, anche `"urgency": "calling"` arriva come notifica normale.

Così un solo canale copre tutto. Iscriviti con Chiamata e chiedi all'agente di inviare gli aggiornamenti di routine come `normal` e di usare `calling` solo quando qualcosa si è rotto.

A differenza di `notificationType` nelle richieste webhook, `urgency` funziona anche sui canali con un modello personalizzato.

### La chiamata richiede Echobell Premium

Le notifiche con chiamata sono una funzione di Echobell Premium. Quando l'agente chiede `calling`, un iscritto senza Premium riceve invece una notifica **urgente**, esattamente come succede con l'app e con i webhook.

### Una chiamata al minuto per canale

Un canale chiama ogni iscritto al massimo una volta al minuto. Se l'agente chiede un'altra chiamata entro quel minuto, ad esempio perché è bloccato in un ciclo di tentativi, l'iscritto riceve invece una notifica **urgente**, che supera comunque le modalità Full Immersion. I webhook e i trigger via email seguono la stessa regola.

L'agente viene informato in entrambi i casi. Il risultato dello strumento elenca ogni ripiego, così l'agente sa che il telefono non ha squillato e può dirtelo invece di dare per scontato che tu sia stato chiamato.

## Cosa riceve l'agente

Ogni chiamata a `notify` restituisce all'agente un breve riepilogo testuale e dei dati strutturati:

```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 | Significato |
|---|---|
| `notificationTriggered` | `true` quando è stata inviata una notifica. |
| `reason` | Perché non è stato inviato nulla: `conditions-not-met` (le [condizioni](/docs/conditions) del canale non erano soddisfatte) o `no-subscribers` (nessuno è iscritto al canale). `null` quando è stata inviata una notifica. |
| `requestedUrgency` | L'`urgency` richiesta dall'agente, oppure `null` se l'ha omessa. |
| `recipients` | Quanti iscritti sono stati avvisati. |
| `deliveredUrgency` | Quanti iscritti hanno ricevuto ciascun livello. |
| `fallbacks` | Gli iscritti che hanno ricevuto un livello più basso di quello richiesto, e il motivo: `premium-required` (la chiamata richiede Premium), `subscriber-setting` (il livello scelto dall'iscritto per il canale è più basso) o `call-cooldown` (il canale ha già chiamato quell'iscritto nell'ultimo minuto). |

## Canali senza modello e canali con modello

Il server MCP funziona con entrambi i tipi di canale:

- I **canali senza modello** (l'impostazione predefinita) mostrano `title` e `body` esattamente come li invia l'agente.
- I **canali con modello** (con **Modello personalizzato** attivo nelle **Impostazioni avanzate**) costruiscono la notifica a partire dai tuoi [modelli](/docs/template). `title`, `body`, `link`, `externalLink` e `urgency` sono disponibili come variabili del modello, e le [condizioni](/docs/conditions) del canale continuano a valere. Se le condizioni non sono soddisfatte, non viene inviato nulla e l'agente riceve `reason: "conditions-not-met"`.

## Esempi di prompt

Una volta collegato il server, chiedi le notifiche con parole tue:

- "Esegui tutta la suite di test e avvisami con Echobell quando hai finito."
- "Fai il refactoring del modulo dei pagamenti. Mandami un avviso Echobell urgente se ti serve una mia decisione."
- "Fai il deploy in staging. Chiamami se il deploy fallisce, altrimenti mandami una notifica normale con l'URL."
- "Quando la migrazione è finita, avvisami con un riepilogo e un link alla pull request."

Per renderlo un'abitudine, aggiungi una riga come questa al file di istruzioni del tuo agente (`CLAUDE.md`, `AGENTS.md`, `.cursorrules` e così via):

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

## Sicurezza

- **Il token è la credenziale.** Chiunque abbia l'URL MCP (o il token) può inviare notifiche agli iscritti del canale. Non permette di leggere nulla né di modificare il tuo account: l'unica cosa che consente è inviare notifiche.
- **Tienilo fuori dai file condivisi.** Non includere nel repository un file di configurazione che contiene la forma con URL. Per la configurazione di progetto, usa la [forma con header](#forma-con-header) con una richiesta di input o una variabile d'ambiente.
- **Revoca l'accesso reimpostando il token del trigger.** Apri il canale nell'app e reimposta il suo token del trigger. Il vecchio URL MCP smette subito di funzionare (le richieste ricevono `401 Unauthorized`), e lo stesso vale per il vecchio URL webhook. Aggiorna i tuoi agenti e chi chiama il webhook con il nuovo token.

## Limiti ed errori

- **Limite di frequenza**: ogni token accetta fino a 120 richieste MCP al minuto. Le richieste MCP hanno un budget proprio, separato da quello delle richieste webhook del canale.
- **401 Unauthorized**: il token manca, è sbagliato o è stato reimpostato.

## Approfondimenti

- [Webhook](/docs/webhook) — attivare lo stesso canale da script, CI e altri servizi
- [Tipi di notifica](/docs/notification) — le differenze tra Normale, Urgente e Chiamata
- [Modelli](/docs/template) e [Condizioni](/docs/conditions) — dare forma alle notifiche e filtrarle