I canali sono in anteprima di ricerca e richiedono Claude Code v2.1.80 o successivo. Richiedono l’accesso a claude.ai. L’autenticazione tramite console e chiave API non è supportata. Le organizzazioni Team ed Enterprise devono abilitarli esplicitamente.
- Panoramica: come funzionano i canali
- Cosa ti serve: requisiti e passaggi generali
- Esempio: crea un ricevitore webhook: una procedura dettagliata minima unidirezionale
- Opzioni del server: i campi del costruttore
- Formato di notifica: il payload dell’evento
- Esponi uno strumento di risposta: consenti a Claude di inviare messaggi indietro
- Gating dei messaggi in entrata: controlli del mittente per prevenire l’iniezione di prompt
- Inoltro delle richieste di autorizzazione: inoltra i prompt di approvazione dello strumento ai canali remoti
Panoramica
Un canale è un server MCP che viene eseguito sulla stessa macchina di Claude Code. Claude Code lo genera come un sottoprocesso e comunica tramite stdio. Il tuo server di canale è il ponte tra i sistemi esterni e la sessione di Claude Code:- Piattaforme di chat (Telegram, Discord): il tuo plugin viene eseguito localmente e interroga l’API della piattaforma per i nuovi messaggi. Quando qualcuno invia un DM al tuo bot, il plugin riceve il messaggio e lo inoltra a Claude. Nessun URL da esporre.
- Webhook (CI, monitoraggio): il tuo server ascolta su una porta HTTP locale. I sistemi esterni POST a quella porta e il tuo server invia il payload a Claude.
Cosa ti serve
L’unico requisito difficile è il pacchetto@modelcontextprotocol/sdk e un runtime compatibile con Node.js. Bun, Node e Deno funzionano tutti. I plugin precostruiti nell’anteprima di ricerca utilizzano Bun, ma il tuo canale non deve necessariamente.
Il tuo server deve:
- Dichiarare la capacità
claude/channelin modo che Claude Code registri un listener di notifica - Emettere eventi
notifications/claude/channelquando accade qualcosa - Connettersi tramite trasporto stdio (Claude Code genera il tuo server come un sottoprocesso)
--dangerously-load-development-channels per testare localmente. Vedi Test durante l’anteprima di ricerca per i dettagli.
Esempio: crea un ricevitore webhook
Questa procedura dettagliata crea un server a file singolo che ascolta le richieste HTTP e le inoltra nella tua sessione di Claude Code. Alla fine, qualsiasi cosa possa inviare un HTTP POST, come una pipeline CI, un avviso di monitoraggio o un comandocurl, può inviare eventi a Claude.
Questo esempio utilizza Bun come runtime per il suo server HTTP integrato e il supporto di TypeScript. Puoi utilizzare Node o Deno invece; l’unico requisito è l’SDK MCP.
Scrivi il server di canale
Crea un file chiamato Il file fa tre cose in ordine:
webhook.ts. Questo è l’intero server di canale: si connette a Claude Code tramite stdio e ascolta i POST HTTP sulla porta 8788. Quando arriva una richiesta, invia il corpo a Claude come evento di canale.webhook.ts
- Configurazione del server: crea il server MCP con
claude/channelnelle sue capacità, che è ciò che dice a Claude Code che questo è un canale. La stringainstructionsva nel prompt di sistema di Claude: dì a Claude quali eventi aspettarsi, se rispondere e come instradare le risposte se dovrebbe. - Connessione stdio: si connette a Claude Code tramite stdin/stdout. Questo è standard per qualsiasi server MCP: Claude Code lo genera come un sottoprocesso.
- Listener HTTP: avvia un server web locale sulla porta 8788. Ogni corpo POST viene inoltrato a Claude come evento di canale tramite
mcp.notification(). Ilcontentdiventa il corpo dell’evento e ogni vocemetadiventa un attributo sul tag<channel>. Il listener ha bisogno dell’accesso all’istanzamcp, quindi viene eseguito nello stesso processo. Potresti dividerlo in moduli separati per un progetto più grande.
Registra il tuo server con Claude Code
Aggiungi il server alla tua configurazione MCP in modo che Claude Code sappia come avviarlo. Per un Claude Code legge la tua configurazione MCP all’avvio e genera ogni server come un sottoprocesso.
.mcp.json a livello di progetto nella stessa directory, usa un percorso relativo. Per la configurazione a livello di utente in ~/.claude.json, usa il percorso assoluto completo in modo che il server possa essere trovato da qualsiasi progetto:.mcp.json
Testalo
Durante l’anteprima di ricerca, i canali personalizzati non sono nella lista di approvazione, quindi avvia Claude Code con il flag di sviluppo:Quando Claude Code si avvia, legge la tua configurazione MCP, genera il tuo Il payload arriva nella tua sessione di Claude Code come un tag Nel tuo terminale di Claude Code, vedrai Claude ricevere il messaggio e iniziare a rispondere: leggendo file, eseguendo comandi o qualsiasi cosa il messaggio richieda. Questo è un canale unidirezionale, quindi Claude agisce nella tua sessione ma non invia nulla indietro tramite il webhook. Per aggiungere risposte, vedi Esponi uno strumento di risposta.Se l’evento non arriva, la diagnosi dipende da ciò che
webhook.ts come un sottoprocesso e il listener HTTP si avvia automaticamente sulla porta che hai configurato (8788 in questo esempio). Non è necessario eseguire il server da solo.Se vedi “bloccato dalla politica dell’organizzazione”, il tuo amministratore Team o Enterprise deve prima abilitare i canali.In un terminale separato, simula un webhook inviando un HTTP POST con un messaggio al tuo server. Questo esempio invia un avviso di errore CI alla porta 8788 (o qualsiasi porta tu abbia configurato):<channel>:curl ha restituito:curlha successo ma nulla raggiunge Claude: esegui/mcpnella tua sessione per controllare lo stato del server. “Impossibile connettersi” di solito significa un errore di dipendenza o importazione nel tuo file server; controlla il log di debug in~/.claude/debug/<session-id>.txtper la traccia stderr.curlfallisce con “connessione rifiutata”: la porta non è ancora associata o un processo stantio da un’esecuzione precedente la sta mantenendo.lsof -i :<port>mostra cosa sta ascoltando;killil processo stantio prima di riavviare la tua sessione.
Test durante l’anteprima di ricerca
Durante l’anteprima di ricerca, ogni canale deve essere nella lista di approvazione approvata per registrarsi. Il flag di sviluppo bypassa la lista di approvazione per voci specifiche dopo un prompt di conferma. Questo esempio mostra entrambi i tipi di voce:--channels non estende il bypass alle voci --channels. Durante l’anteprima di ricerca, la lista di approvazione approvata è curata da Anthropic, quindi il tuo canale rimane sul flag di sviluppo mentre lo costruisci e lo testi.
Questo flag salta solo la lista di approvazione. La politica organizzativa
channelsEnabled si applica comunque. Non usarla per eseguire canali da fonti non attendibili.Opzioni del server
Un canale imposta queste opzioni nel costruttoreServer. I campi instructions e capabilities.tools sono MCP standard; capabilities.experimental['claude/channel'] e capabilities.experimental['claude/channel/permission'] sono le aggiunte specifiche del canale:
| Campo | Tipo | Descrizione |
|---|---|---|
capabilities.experimental['claude/channel'] | object | Obbligatorio. Sempre {}. La presenza registra il listener di notifica. |
capabilities.experimental['claude/channel/permission'] | object | Facoltativo. Sempre {}. Dichiara che questo canale può ricevere richieste di inoltro delle autorizzazioni. Quando dichiarato, Claude Code inoltra i prompt di approvazione dello strumento al tuo canale in modo da poter approvare o negare da remoto. Vedi Inoltro delle richieste di autorizzazione. |
capabilities.tools | object | Solo bidirezionale. Sempre {}. Capacità dello strumento MCP standard. Vedi Esponi uno strumento di risposta. |
instructions | string | Consigliato. Aggiunto al prompt di sistema di Claude. Dì a Claude quali eventi aspettarsi, cosa significano gli attributi del tag <channel>, se rispondere e, se sì, quale strumento usare e quale attributo passare indietro (come chat_id). |
capabilities.tools. Questo esempio mostra una configurazione bidirezionale con la capacità del canale, gli strumenti e le istruzioni impostate:
mcp.notification() con il metodo notifications/claude/channel. I parametri sono nella sezione successiva.
Formato di notifica
Il tuo server emettenotifications/claude/channel con due parametri:
| Campo | Tipo | Descrizione |
|---|---|---|
content | string | Il corpo dell’evento. Consegnato come il corpo del tag <channel>. |
meta | Record<string, string> | Facoltativo. Ogni voce diventa un attributo sul tag <channel> per il contesto di instradamento come ID chat, nome del mittente o gravità dell’avviso. Le chiavi devono essere identificatori: solo lettere, cifre e sottolineature. Le chiavi contenenti trattini o altri caratteri vengono silenziosamente eliminate. |
mcp.notification() sull’istanza Server. Questo esempio invia un avviso di errore CI con due chiavi meta:
<channel>. L’attributo source viene impostato automaticamente dal nome configurato del tuo server:
Esponi uno strumento di risposta
Se il tuo canale è bidirezionale, come un bridge di chat piuttosto che un inoltro di avvisi, esponi uno strumento MCP standard che Claude può chiamare per inviare messaggi indietro. Nulla della registrazione dello strumento è specifico del canale. Uno strumento di risposta ha tre componenti:- Una voce
tools: {}nelle capacità del tuo costruttoreServerin modo che Claude Code scopra lo strumento - Handler dello strumento che definiscono lo schema dello strumento e implementano la logica di invio
- Una stringa
instructionsnel tuo costruttoreServerche dice a Claude quando e come chiamare lo strumento
Abilita la scoperta dello strumento
Nel tuo costruttore
Server in webhook.ts, aggiungi tools: {} alle capacità in modo che Claude Code sappia che il tuo server offre strumenti:Registra lo strumento di risposta
Aggiungi quanto segue a
webhook.ts. L’import va in cima al file con i tuoi altri import; i due handler vanno tra il costruttore Server e mcp.connect(). Questo registra uno strumento reply che Claude può chiamare con un chat_id e text:webhook.ts completo con supporto bidirezionale. Le risposte in uscita vengono trasmesse su GET /events utilizzando Server-Sent Events (SSE), quindi curl -N localhost:8788/events può guardarle dal vivo; la chat in entrata arriva su POST /:
"Full
Gating dei messaggi in entrata
Un canale senza gating è un vettore di iniezione di prompt. Chiunque possa raggiungere il tuo endpoint può mettere testo davanti a Claude. Un canale che ascolta una piattaforma di chat o un endpoint pubblico ha bisogno di un vero controllo del mittente prima di emettere qualsiasi cosa. Controlla il mittente rispetto a una lista di approvazione prima di chiamaremcp.notification(). Questo esempio elimina qualsiasi messaggio da un mittente non nel set:
message.from.id nell’esempio, non message.chat.id. Nelle chat di gruppo, questi differiscono e il gating sulla stanza permetterebbe a chiunque in un gruppo approvato di iniettare messaggi nella sessione.
I canali Telegram e Discord fanno il gating su una lista di approvazione del mittente allo stesso modo. Avviano la lista tramite accoppiamento: l’utente invia un DM al bot, il bot risponde con un codice di accoppiamento, l’utente lo approva nella sua sessione di Claude Code e il suo ID della piattaforma viene aggiunto. Vedi entrambe le implementazioni per il flusso di accoppiamento completo. Il canale iMessage adotta un approccio diverso: rileva gli indirizzi dell’utente dal database dei Messaggi all’avvio e li lascia passare automaticamente, con altri mittenti aggiunti per handle.
Inoltro delle richieste di autorizzazione
L’inoltro delle autorizzazioni richiede Claude Code v2.1.81 o successivo. Le versioni precedenti ignorano la capacità
claude/channel/permission.Bash, Write e Edit. La fiducia del progetto e i dialoghi di consenso del server MCP non vengono inoltrati; quelli appaiono solo nel terminale locale.
Come funziona l’inoltro
Quando si apre un prompt di autorizzazione, il ciclo di inoltro ha quattro passaggi:- Claude Code genera un breve ID di richiesta e notifica il tuo server
- Il tuo server inoltra il prompt e l’ID alla tua app di chat
- L’utente remoto risponde con un sì o no e quell’ID
- Il tuo gestore in entrata analizza la risposta in un verdetto e Claude Code lo applica solo se l’ID corrisponde a una richiesta aperta
Campi della richiesta di autorizzazione
La notifica in uscita da Claude Code ènotifications/claude/channel/permission_request. Come la notifica del canale, il trasporto è MCP standard ma il metodo e lo schema sono estensioni di Claude Code. L’oggetto params ha quattro campi stringa che il tuo server formatta nel prompt in uscita:
| Campo | Descrizione |
|---|---|
request_id | Cinque lettere minuscole tratte da a-z senza l, quindi non legge mai come 1 o I quando digitato su un telefono. Includilo nel tuo prompt in uscita in modo che possa essere ripetuto nella risposta. Claude Code accetta solo un verdetto che porta un ID che ha emesso. La finestra di dialogo del terminale locale non visualizza questo ID, quindi il tuo gestore in uscita è l’unico modo per apprenderlo. |
tool_name | Nome dello strumento che Claude vuole usare, ad esempio Bash o Write. |
description | Riepilogo leggibile di cosa fa questa specifica chiamata dello strumento, lo stesso testo che la finestra di dialogo del terminale locale mostra. Per una chiamata Bash questo è la descrizione di Claude del comando, o il comando stesso se nessuno è stato fornito. |
input_preview | Gli argomenti dello strumento come stringa JSON, troncati a 200 caratteri. Per Bash questo è il comando; per Write è il percorso del file e un prefisso del contenuto. Omettilo dal tuo prompt se hai solo spazio per un messaggio di una riga. Il tuo server decide cosa mostrare. |
notifications/claude/channel/permission con due campi: request_id che ripete l’ID sopra e behavior impostato su 'allow' o 'deny'. Allow consente alla chiamata dello strumento di procedere; deny la rifiuta, lo stesso che rispondere No nella finestra di dialogo locale. Nessun verdetto influisce sulle chiamate future.
Aggiungi inoltro a un bridge di chat
L’aggiunta dell’inoltro delle autorizzazioni a un canale bidirezionale richiede tre componenti:- Una voce
claude/channel/permission: {}sotto le capacitàexperimentalnel tuo costruttoreServerin modo che Claude Code sappia di inoltrare i prompt - Un gestore di notifica per
notifications/claude/channel/permission_requestche formatta il prompt e lo invia tramite l’API della tua piattaforma - Un controllo nel tuo gestore di messaggi in entrata che riconosce
yes <id>ono <id>e emette una notifica di verdettonotifications/claude/channel/permissioninvece di inoltrare il testo a Claude
Dichiara la capacità di autorizzazione
Nel tuo costruttore
Server, aggiungi claude/channel/permission: {} accanto a claude/channel sotto experimental:Gestisci la richiesta in entrata
Registra un gestore di notifica tra il tuo costruttore
Server e mcp.connect(). Claude Code lo chiama con i quattro campi di richiesta quando si apre una finestra di dialogo di autorizzazione. Il tuo gestore formatta il prompt per la tua piattaforma e include istruzioni per rispondere con l’ID:Intercetta il verdetto nel tuo gestore in entrata
Il tuo gestore in entrata è il ciclo o il callback che riceve messaggi dalla tua piattaforma: lo stesso posto dove fai il gating sul mittente e emetti
notifications/claude/channel per inoltrare la chat a Claude. Aggiungi un controllo prima della chiamata di inoltro della chat che riconosce il formato del verdetto e emette la notifica di autorizzazione invece.L’espressione regolare corrisponde al formato dell’ID che Claude Code genera: cinque lettere, mai l. Il flag /i tollera l’autocorrezione del telefono che capitalizza la risposta; minuscola l’ID catturato prima di inviarlo indietro.- Formato diverso: l’espressione regolare del tuo gestore in entrata non corrisponde, quindi testo come
approve itoyessenza un ID passa come messaggio normale a Claude. - Formato corretto, ID sbagliato: il tuo server emette un verdetto, ma Claude Code non trova nessuna richiesta aperta con quell’ID e lo elimina silenziosamente.
Esempio completo
Ilwebhook.ts assemblato di seguito combina tutte e tre le estensioni da questa pagina: lo strumento di risposta, il gating del mittente e l’inoltro delle autorizzazioni. Se stai iniziando qui, avrai anche bisogno della configurazione del progetto e della voce .mcp.json dalla procedura dettagliata iniziale.
Per rendere entrambe le direzioni testabili da curl, il listener HTTP serve due percorsi:
GET /events: mantiene aperto un flusso SSE e invia ogni messaggio in uscita come una rigadata:, quindicurl -Npuò guardare le risposte di Claude e i prompt di autorizzazione arrivare dal vivo.POST /: il lato in entrata, lo stesso gestore di prima, ora con il controllo del formato del verdetto inserito prima del ramo di inoltro della chat.
"Full
webhook.ts:
/events, incluso l’ID di cinque lettere. Approvalo dal lato remoto:
reply e atterra anche nel flusso.
I tre pezzi specifici del canale in questo file:
- Capacità nel costruttore
Server:claude/channelregistra il listener di notifica,claude/channel/permissionopta per l’inoltro delle autorizzazioni,toolsconsente a Claude di scoprire lo strumento di risposta. - Percorsi in uscita: il gestore dello strumento
replyè ciò che Claude chiama per le risposte conversazionali; il gestore di notificaPermissionRequestSchemaè ciò che Claude Code chiama quando si apre una finestra di dialogo di autorizzazione. Entrambi chiamanosend()per trasmettere su/events, ma vengono attivati da parti diverse del sistema. - Gestore HTTP:
GET /eventsmantiene aperto un flusso SSE in modo che curl possa guardare l’uscita dal vivo;POSTè in entrata, gated sull’intestazioneX-Sender. Un corpoyes <id>ono <id>va a Claude Code come notifica di verdetto e non raggiunge mai Claude; qualsiasi altra cosa viene inoltrata a Claude come evento di canale.
Pacchetto come plugin
Per rendere il tuo canale installabile e condivisibile, avvolgilo in un plugin e pubblicalo in un marketplace. Gli utenti lo installano con/plugin install, quindi lo abilitano per sessione con --channels plugin:<name>@<marketplace>.
Un canale pubblicato nel tuo marketplace ha ancora bisogno di --dangerously-load-development-channels per essere eseguito, poiché non è nella lista di approvazione. Per aggiungerlo, invialo al marketplace ufficiale. I plugin di canale passano attraverso la revisione della sicurezza prima di essere approvati. Nei piani Team ed Enterprise, un amministratore può invece includere il tuo plugin nella lista allowedChannelPlugins dell’organizzazione, che sostituisce la lista di approvazione predefinita di Anthropic.
Vedi anche
- Canali per installare e utilizzare Telegram, Discord, iMessage o la demo fakechat, e per abilitare i canali per un’organizzazione Team o Enterprise
- Implementazioni di canali funzionanti per il codice del server completo con flussi di accoppiamento, strumenti di risposta e allegati di file
- MCP per il protocollo sottostante che i server di canale implementano
- Plugin per pacchettizzare il tuo canale in modo che gli utenti possano installarlo con
/plugin install