Les canaux sont en aperçu de recherche et nécessitent Claude Code v2.1.80 ou ultérieur. Ils nécessitent une connexion claude.ai. L’authentification par console et clé API n’est pas prise en charge. Les organisations Team et Enterprise doivent les activer explicitement.
- Aperçu : comment fonctionnent les canaux
- Ce dont vous avez besoin : exigences et étapes générales
- Exemple : créer un récepteur de webhook : une procédure pas à pas unidirectionnelle minimale
- Options du serveur : les champs du constructeur
- Format de notification : la charge utile de l’événement
- Exposer un outil de réponse : permettre à Claude d’envoyer des messages en retour
- Contrôler les messages entrants : vérifications de l’expéditeur pour prévenir l’injection de requête
- Relayer les invites de permission : transmettre les invites d’approbation d’outils aux canaux distants
Aperçu
Un canal est un serveur MCP qui s’exécute sur la même machine que Claude Code. Claude Code le lance en tant que sous-processus et communique via stdio. Votre serveur de canal est le pont entre les systèmes externes et la session Claude Code :- Plateformes de chat (Telegram, Discord) : votre plugin s’exécute localement et interroge l’API de la plateforme pour les nouveaux messages. Quand quelqu’un envoie un message direct à votre bot, le plugin reçoit le message et le transmet à Claude. Aucune URL à exposer.
- Webhooks (CI, surveillance) : votre serveur écoute sur un port HTTP local. Les systèmes externes envoient des POST à ce port, et votre serveur envoie la charge utile à Claude.
Ce dont vous avez besoin
La seule exigence stricte est le package@modelcontextprotocol/sdk et un runtime compatible Node.js. Bun, Node et Deno fonctionnent tous. Les plugins pré-construits dans l’aperçu de recherche utilisent Bun, mais votre canal n’a pas besoin de le faire.
Votre serveur doit :
- Déclarer la capacité
claude/channelafin que Claude Code enregistre un écouteur de notification - Émettre des événements
notifications/claude/channelquand quelque chose se produit - Se connecter via transport stdio (Claude Code lance votre serveur en tant que sous-processus)
--dangerously-load-development-channels pour tester localement. Consultez Tester pendant l’aperçu de recherche pour plus de détails.
Exemple : créer un récepteur de webhook
Cette procédure pas à pas crée un serveur d’un seul fichier qui écoute les requêtes HTTP et les transmet dans votre session Claude Code. À la fin, tout ce qui peut envoyer un HTTP POST, comme un pipeline CI, une alerte de surveillance ou une commandecurl, peut envoyer des événements à Claude.
Cet exemple utilise Bun comme runtime pour son serveur HTTP intégré et son support TypeScript. Vous pouvez utiliser Node ou Deno à la place ; la seule exigence est le SDK MCP.
Écrire le serveur de canal
Créez un fichier appelé Le fichier fait trois choses dans l’ordre :
webhook.ts. C’est votre serveur de canal entier : il se connecte à Claude Code via stdio, et il écoute les POST HTTP sur le port 8788. Quand une requête arrive, il envoie le corps à Claude en tant qu’événement de canal.webhook.ts
- Configuration du serveur : crée le serveur MCP avec
claude/channeldans ses capacités, ce qui indique à Claude Code que c’est un canal. La chaîneinstructionsva dans l’invite système de Claude : dites à Claude quels événements attendre, s’il faut répondre et comment router les réponses si c’est le cas. - Connexion stdio : se connecte à Claude Code via stdin/stdout. C’est standard pour tout serveur MCP : Claude Code le lance en tant que sous-processus.
- Écouteur HTTP : démarre un serveur web local sur le port 8788. Chaque corps POST est transmis à Claude en tant qu’événement de canal via
mcp.notification(). Lecontentdevient le corps de l’événement, et chaque entréemetadevient un attribut sur la balise<channel>. L’écouteur a besoin d’accès à l’instancemcp, donc il s’exécute dans le même processus. Vous pourriez le diviser en modules séparés pour un projet plus grand.
Enregistrer votre serveur avec Claude Code
Ajoutez le serveur à votre configuration MCP afin que Claude Code sache comment le démarrer. Pour un Claude Code lit votre configuration MCP au démarrage et lance chaque serveur en tant que sous-processus.
.mcp.json au niveau du projet dans le même répertoire, utilisez un chemin relatif. Pour la configuration au niveau de l’utilisateur dans ~/.claude.json, utilisez le chemin absolu complet afin que le serveur puisse être trouvé à partir de n’importe quel projet :.mcp.json
Le tester
Pendant l’aperçu de recherche, les canaux personnalisés ne sont pas sur la liste d’approbation, donc démarrez Claude Code avec le drapeau de développement :Quand Claude Code démarre, il lit votre configuration MCP, lance votre La charge utile arrive dans votre session Claude Code en tant que balise Dans votre terminal Claude Code, vous verrez Claude recevoir le message et commencer à répondre : lire des fichiers, exécuter des commandes ou tout ce que le message demande. C’est un canal unidirectionnel, donc Claude agit dans votre session mais ne renvoie rien via le webhook. Pour ajouter des réponses, consultez Exposer un outil de réponse.Si l’événement n’arrive pas, le diagnostic dépend de ce que
webhook.ts en tant que sous-processus, et l’écouteur HTTP démarre automatiquement sur le port que vous avez configuré (8788 dans cet exemple). Vous n’avez pas besoin de lancer le serveur vous-même.Si vous voyez ’ bloqué par la politique de l’organisation ’, votre administrateur Team ou Enterprise doit d’abord activer les canaux.Dans un terminal séparé, simulez un webhook en envoyant un HTTP POST avec un message à votre serveur. Cet exemple envoie une alerte d’échec CI au port 8788 (ou quel que soit le port que vous avez configuré) :<channel> :curl a retourné :curlréussit mais rien n’atteint Claude : exécutez/mcpdans votre session pour vérifier l’état du serveur. « Impossible de se connecter » signifie généralement une erreur de dépendance ou d’importation dans votre fichier serveur ; vérifiez le journal de débogage à~/.claude/debug/<session-id>.txtpour la trace stderr.curléchoue avec « connexion refusée » : le port n’est pas encore lié ou un processus obsolète d’une exécution antérieure le maintient.lsof -i :<port>montre ce qui écoute ;killle processus obsolète avant de redémarrer votre session.
Tester pendant l’aperçu de recherche
Pendant l’aperçu de recherche, chaque canal doit être sur la liste d’approbation pour s’enregistrer. Le drapeau de développement contourne la liste d’approbation pour des entrées spécifiques après une invite de confirmation. Cet exemple montre les deux types d’entrée :--channels n’étend pas le contournement aux entrées --channels. Pendant l’aperçu de recherche, la liste d’approbation est organisée par Anthropic, donc votre canal reste sur le drapeau de développement pendant que vous le construisez et le testez.
Ce drapeau ignore uniquement la liste d’approbation. La politique d’organisation
channelsEnabled s’applique toujours. Ne l’utilisez pas pour exécuter des canaux de sources non fiables.Options du serveur
Un canal définit ces options dans le constructeurServer. Les champs instructions et capabilities.tools sont MCP standard ; capabilities.experimental['claude/channel'] et capabilities.experimental['claude/channel/permission'] sont les ajouts spécifiques au canal :
| Champ | Type | Description |
|---|---|---|
capabilities.experimental['claude/channel'] | object | Requis. Toujours {}. La présence enregistre l’écouteur de notification. |
capabilities.experimental['claude/channel/permission'] | object | Optionnel. Toujours {}. Déclare que ce canal peut recevoir des demandes de relais de permission. Quand déclaré, Claude Code transmet les invites d’approbation d’outils à votre canal afin que vous puissiez les approuver ou les refuser à distance. Consultez Relayer les invites de permission. |
capabilities.tools | object | Bidirectionnel uniquement. Toujours {}. Capacité d’outil MCP standard. Consultez Exposer un outil de réponse. |
instructions | string | Recommandé. Ajouté à l’invite système de Claude. Dites à Claude quels événements attendre, ce que les attributs de la balise <channel> signifient, s’il faut répondre et, le cas échéant, quel outil utiliser et quel attribut repasser (comme chat_id). |
capabilities.tools. Cet exemple montre une configuration bidirectionnelle avec la capacité de canal, les outils et les instructions définis :
mcp.notification() avec la méthode notifications/claude/channel. Les paramètres sont dans la section suivante.
Format de notification
Votre serveur émetnotifications/claude/channel avec deux paramètres :
| Champ | Type | Description |
|---|---|---|
content | string | Le corps de l’événement. Livré en tant que corps de la balise <channel>. |
meta | Record<string, string> | Optionnel. Chaque entrée devient un attribut sur la balise <channel> pour le contexte de routage comme l’ID de chat, le nom de l’expéditeur ou la gravité de l’alerte. Les clés doivent être des identifiants : lettres, chiffres et traits de soulignement uniquement. Les clés contenant des tirets ou d’autres caractères sont silencieusement supprimées. |
mcp.notification() sur l’instance Server. Cet exemple envoie une alerte d’échec CI avec deux clés meta :
<channel>. L’attribut source est défini automatiquement à partir du nom configuré de votre serveur :
Exposer un outil de réponse
Si votre canal est bidirectionnel, comme une passerelle de chat plutôt qu’un transmetteur d’alerte, exposez un outil MCP standard que Claude peut appeler pour envoyer des messages en retour. Rien dans l’enregistrement de l’outil n’est spécifique au canal. Un outil de réponse a trois composants :- Une entrée
tools: {}dans les capacités du constructeurServerafin que Claude Code découvre l’outil - Des gestionnaires d’outils qui définissent le schéma de l’outil et implémentent la logique d’envoi
- Une chaîne
instructionsdans le constructeurServerqui indique à Claude quand et comment appeler l’outil
Activer la découverte d'outils
Dans votre constructeur
Server dans webhook.ts, ajoutez tools: {} aux capacités afin que Claude Code sache que votre serveur offre des outils :Enregistrer l'outil de réponse
Ajoutez ce qui suit à
webhook.ts. L’import va en haut du fichier avec vos autres imports ; les deux gestionnaires vont entre le constructeur Server et mcp.connect(). Cela enregistre un outil reply que Claude peut appeler avec un chat_id et un text :webhook.ts complet avec support bidirectionnel. Les réponses sortantes se diffusent via GET /events en utilisant Server-Sent Events (SSE), donc curl -N localhost:8788/events peut les regarder en direct ; le chat entrant arrive sur POST / :
"webhook.ts
Contrôler les messages entrants
Un canal non contrôlé est un vecteur d’injection de requête. Quiconque peut atteindre votre point de terminaison peut mettre du texte devant Claude. Un canal écoutant une plateforme de chat ou un point de terminaison public a besoin d’une vérification d’expéditeur réelle avant d’émettre quoi que ce soit. Vérifiez l’expéditeur par rapport à une liste d’approbation avant d’appelermcp.notification(). Cet exemple supprime tout message d’un expéditeur qui n’est pas dans l’ensemble :
message.from.id dans l’exemple, pas message.chat.id. Dans les chats de groupe, ceux-ci diffèrent, et contrôler sur la salle laisserait quiconque dans un groupe approuvé injecter des messages dans la session.
Les canaux Telegram et Discord contrôlent sur une liste d’approbation d’expéditeur de la même manière. Ils amorçent la liste par appairage : l’utilisateur envoie un message direct au bot, le bot répond avec un code d’appairage, l’utilisateur l’approuve dans sa session Claude Code, et son ID de plateforme est ajouté. Consultez l’une ou l’autre implémentation pour le flux d’appairage complet. Le canal iMessage adopte une approche différente : il détecte les propres adresses de l’utilisateur à partir de la base de données Messages au démarrage et les laisse passer automatiquement, avec d’autres expéditeurs ajoutés par poignée.
Relayer les invites de permission
Le relais de permission nécessite Claude Code v2.1.81 ou ultérieur. Les versions antérieures ignorent la capacité
claude/channel/permission.Bash, Write et Edit. La confiance du projet et les boîtes de dialogue de consentement du serveur MCP ne relaient pas ; celles-ci n’apparaissent que dans le terminal local.
Comment fonctionne le relais
Quand une invite de permission s’ouvre, la boucle de relais a quatre étapes :- Claude Code génère un court ID de demande et notifie votre serveur
- Votre serveur transmet l’invite et l’ID à votre application de chat
- L’utilisateur distant répond par oui ou non et cet ID
- Votre gestionnaire entrant analyse la réponse en un verdict, et Claude Code l’applique uniquement si l’ID correspond à une demande ouverte
Champs de demande de permission
La notification sortante de Claude Code estnotifications/claude/channel/permission_request. Comme la notification de canal, le transport est MCP standard mais la méthode et le schéma sont des extensions Claude Code. L’objet params a quatre champs de chaîne que votre serveur formate dans l’invite sortante :
| Champ | Description |
|---|---|
request_id | Cinq lettres minuscules tirées de a-z sans l, donc cela ne se lit jamais comme un 1 ou un I quand tapé sur un téléphone. Incluez-le dans votre invite sortante afin qu’il puisse être répété dans la réponse. Claude Code n’accepte un verdict que s’il porte un ID qu’il a émis. La boîte de dialogue du terminal local n’affiche pas cet ID, donc votre gestionnaire sortant est le seul moyen de l’apprendre. |
tool_name | Nom de l’outil que Claude veut utiliser, par exemple Bash ou Write. |
description | Résumé lisible par l’homme de ce que cet appel d’outil spécifique fait, le même texte que la boîte de dialogue du terminal local affiche. Pour un appel Bash c’est la description de Claude de la commande, ou la commande elle-même si aucune n’a été donnée. |
input_preview | Les arguments de l’outil sous forme de chaîne JSON, tronqués à 200 caractères. Pour Bash c’est la commande ; pour Write c’est le chemin du fichier et un préfixe du contenu. Omettez-le de votre invite si vous n’avez de la place que pour un message d’une ligne. Votre serveur décide ce qu’il faut afficher. |
notifications/claude/channel/permission avec deux champs : request_id répétant l’ID ci-dessus, et behavior défini sur 'allow' ou 'deny'. Allow laisse l’appel d’outil procéder ; deny le rejette, comme répondre Non dans la boîte de dialogue locale. Aucun verdict n’affecte les appels futurs.
Ajouter le relais à une passerelle de chat
Ajouter le relais de permission à un canal bidirectionnel prend trois composants :- Une entrée
claude/channel/permission: {}sous les capacitésexperimentaldans votre constructeurServerafin que Claude Code sache transmettre les invites - Un gestionnaire de notification pour
notifications/claude/channel/permission_requestqui formate l’invite et l’envoie via votre API de plateforme - Une vérification dans votre gestionnaire de message entrant qui reconnaît
yes <id>ouno <id>et émet une notification de verdictnotifications/claude/channel/permissionau lieu de transmettre le texte à Claude
Déclarer la capacité de permission
Dans votre constructeur
Server, ajoutez claude/channel/permission: {} à côté de claude/channel sous experimental :Gérer la demande entrante
Enregistrez un gestionnaire de notification entre votre constructeur
Server et mcp.connect(). Claude Code l’appelle avec les quatre champs de demande quand une boîte de dialogue de permission s’ouvre. Votre gestionnaire formate l’invite pour votre plateforme et inclut des instructions pour répondre avec l’ID :Intercepter le verdict dans votre gestionnaire entrant
Votre gestionnaire entrant est la boucle ou le rappel qui reçoit les messages de votre plateforme : le même endroit où vous contrôlez sur l’expéditeur et émettez
notifications/claude/channel pour transmettre le chat à Claude. Ajoutez une vérification avant l’appel de transmission de chat qui reconnaît le format du verdict et émet la notification de permission à la place.La regex correspond au format d’ID que Claude Code génère : cinq lettres, jamais l. Le drapeau /i tolère la correction automatique du téléphone en mettant en majuscules la réponse ; mettez en minuscules l’ID capturé avant de le renvoyer.- Format différent : la regex de votre gestionnaire entrant ne correspond pas, donc du texte comme
approve itouyessans ID tombe comme un message normal à Claude. - Format correct, ID incorrect : votre serveur émet un verdict, mais Claude Code ne trouve aucune demande ouverte avec cet ID et le supprime silencieusement.
Exemple complet
Lewebhook.ts assemblé ci-dessous combine les trois extensions de cette page : l’outil de réponse, le contrôle de l’expéditeur et le relais de permission. Si vous commencez ici, vous aurez également besoin de la configuration du projet et de l’entrée .mcp.json de la procédure pas à pas initiale.
Pour rendre les deux directions testables à partir de curl, l’écouteur HTTP sert deux chemins :
GET /events: maintient un flux SSE ouvert et envoie chaque message sortant en tant que lignedata:, donccurl -Npeut regarder les réponses et les invites de permission de Claude arriver en direct.POST /: le côté entrant, le même gestionnaire qu’avant, maintenant avec la vérification du format du verdict insérée avant la branche de transmission de chat.
"webhook.ts
webhook.ts :
/events, y compris l’ID à cinq lettres. Approuvez-le du côté distant :
reply et atterrit aussi dans le flux.
Les trois pièces spécifiques au canal dans ce fichier :
- Capacités dans le constructeur
Server:claude/channelenregistre l’écouteur de notification,claude/channel/permissionopte pour le relais de permission,toolslaisse Claude découvrir l’outil de réponse. - Chemins sortants : le gestionnaire de l’outil
replyest ce que Claude appelle pour les réponses conversationnelles ; le gestionnaire de notificationPermissionRequestSchemaest ce que Claude Code appelle quand une boîte de dialogue de permission s’ouvre. Les deux appellentsend()pour diffuser sur/events, mais ils sont déclenchés par différentes parties du système. - Gestionnaire HTTP :
GET /eventsmaintient un flux SSE ouvert afin que curl puisse regarder la sortie en direct ;POSTest entrant, contrôlé sur l’en-têteX-Sender. Un corpsyes <id>ouno <id>va à Claude Code en tant que notification de verdict et n’atteint jamais Claude ; tout le reste est transmis à Claude en tant qu’événement de canal.
Empaqueter en tant que plugin
Pour rendre votre canal installable et partageable, enveloppez-le dans un plugin et publiez-le sur un marketplace. Les utilisateurs l’installent avec/plugin install, puis l’activent par session avec --channels plugin:<name>@<marketplace>.
Un canal publié sur votre propre marketplace a toujours besoin de --dangerously-load-development-channels pour s’exécuter, car il n’est pas sur la liste d’approbation. Pour le faire ajouter, soumettez-le au marketplace officiel. Les plugins de canal passent par un examen de sécurité avant d’être approuvés. Sur les plans Team et Enterprise, un administrateur peut plutôt inclure votre plugin dans la liste allowedChannelPlugins de l’organisation, qui remplace la liste d’approbation Anthropic par défaut.
Voir aussi
- Canaux pour installer et utiliser Telegram, Discord, iMessage ou la démo fakechat, et pour activer les canaux pour une organisation Team ou Enterprise
- Implémentations de canaux fonctionnels pour le code serveur complet avec flux d’appairage, outils de réponse et pièces jointes
- MCP pour le protocole sous-jacent que les serveurs de canal implémentent
- Plugins pour empaqueter votre canal afin que les utilisateurs puissent l’installer avec
/plugin install