Les canaux sont en aperçu de recherche. 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 et le comportement de livraison
- 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
--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
Ce guide pas à pas crée un serveur en un seul fichier qui écoute les requêtes HTTP et les transmet à votre session Claude Code. À la fin, tout ce qui peut envoyer un HTTP POST, comme un pipeline CI, une alerte de monitoring ou une commandecurl, pourra envoyer des événements à Claude.
Cet exemple utilise Bun comme runtime pour son serveur HTTP intégré et sa prise en charge de TypeScript. Vous pouvez utiliser Node ou Deno à la place ; la seule exigence est le MCP SDK.
1
Créer le projet
Les exemples de relais de permissions importent
zod directement, il est donc installé en même temps que le MCP SDK. Créez un nouveau répertoire et installez les deux :2
Écrire le serveur de canal
Créez un fichier nommé Le fichier configure le serveur, se connecte via stdio et démarre un listener HTTP, dans cet ordre :
webhook.ts. C’est l’intégralité de votre serveur de canal : il se connecte à Claude Code via stdio et écoute les HTTP POST sur le port 8788. Lorsqu’une requête arrive, il transmet le corps à Claude sous forme d’é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 qu’il s’agit d’un canal. Claude Code transmet la chaîneinstructionsà Claude comme contexte lorsque le serveur se connecte : indiquez à Claude quels événements attendre, s’il doit répondre et, le cas échéant, comment acheminer les réponses. - Connexion stdio : se connecte à Claude Code via stdin/stdout. C’est la norme pour tout serveur MCP.
- Listener HTTP : démarre un serveur web local sur le port 8788. Chaque corps de POST est transmis à Claude comme événement de canal via
mcp.notification(). Lecontentdevient le corps de l’événement, et chaque entréemetadevient un attribut de la balise<channel>. Le listener a besoin d’accéder à l’instancemcp, il s’exécute donc dans le même processus. Vous pourriez le séparer en modules distincts pour un projet plus important.
3
Enregistrer votre serveur auprès de Claude Code
Ajoutez le serveur à votre configuration MCP pour 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 une configuration au niveau utilisateur dans ~/.claude.json, utilisez le chemin absolu complet afin que le serveur soit trouvé depuis n’importe quel projet :.mcp.json
4
Le tester
Pendant la research preview, les canaux personnalisés ne figurent pas sur la liste d’autorisation, démarrez donc Claude Code avec le flag de développement :Claude Code affiche d’abord une boîte de dialogue d’avertissement en plein écran listant les canaux de développement que vous chargez. Sélectionnez I am using this for local development pour continuer, ou Exit pour quitter.La première fois que vous démarrez une session dans ce projet, Claude Code demande également votre consentement avant d’utiliser le nouveau serveur de Le payload arrive dans le contexte de Claude sous forme de balise Votre terminal affiche l’événement sous forme de résumé sur une ligne,
.mcp.json. La boîte de dialogue indique « New MCP server found in this project: webhook ». Sélectionnez Use this MCP server pour continuer.Une fois que vous avez accepté, Claude Code lance votre webhook.ts en tant que sous-processus, et le listener HTTP démarre automatiquement sur le port que vous avez configuré, 8788 dans cet exemple. Vous n’avez pas besoin d’exécuter le serveur vous-même.Un avis grisé sous la bannière de démarrage confirme que le canal est enregistré : Channels (experimental) messages from server:webhook inject directly in this session · restart without --dangerously-load-development-channels to stop.Si vous voyez « blocked by org policy », l’administrateur de votre organisation doit d’abord activer les canaux.Dans un terminal séparé, simulez un webhook en envoyant un HTTP POST contenant un message à votre serveur. Cet exemple envoie une alerte d’échec CI au port 8788 (ou à celui que vous avez configuré) :<channel> :← webhook: build failed on main: https://ci.example.com/run/1234, plutôt que la balise brute. Vous verrez ensuite Claude commencer à répondre : lire des fichiers, exécuter des commandes, ou tout ce que le message demande. Il s’agit d’un canal unidirectionnel : 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 curl a renvoyé :curlréussit mais rien n’atteint Claude : exécutez/mcpdans votre session pour vérifier l’état du serveur. Un étatfailedsignifie généralement une erreur de dépendance ou d’import dans votre fichier serveur. Pour voir la trace stderr, redémarrez avecclaude --debug --dangerously-load-development-channels server:webhooket consultez le log de débogage dans~/.claude/debug/<session-id>.txt.curléchoue avec « connection refused » : soit le port n’est pas encore lié, soit un processus résiduel d’une exécution précédente l’occupe.lsof -i :<port>indique ce qui écoute ; arrêtez le processus résiduel aveckillavant 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 :-p ou via l’Agent SDK, Claude Code ignore le flag et le canal ne s’enregistre pas.
Le contournement est par entrée. Combiner ce drapeau avec --channels n’étend pas le contournement aux entrées --channels. Pendant l’aperçu de recherche, votre canal n’est pas sur la liste d’approbation approuvée, donc il 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 :
Pour créer un canal unidirectionnel, omettez
capabilities.tools. Cet exemple montre une configuration bidirectionnelle avec la capacité de canal, les outils et les instructions définis :
Format de notification
Votre serveur émetnotifications/claude/channel avec deux paramètres :
Votre serveur envoie des événements en appelant
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 :
await sur mcp.notification() se résout quand le message est écrit au transport, pas quand Claude l’a traité. Si la session n’a pas chargé votre serveur en tant que canal, ou si la politique d’organisation le bloque, les événements sont supprimés silencieusement sans erreur retournée à votre serveur.
Si vous avez besoin d’une confirmation de livraison, suivez l’état de l’événement dans votre serveur et exposez un outil de réponse que Claude peut appeler pour signaler le statut en retour.
Les événements s’accumulent dans la session et sont traités dans l’ordre. Si plusieurs notifications arrivent pendant que Claude est occupé, elles sont livrées ensemble au prochain tour et Claude les traite comme un groupe. Pour traiter les flux d’événements indépendants en parallèle, exécutez des sessions séparées.
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
1
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 :2
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 :3
Mettre à jour les instructions
Mettez à jour la chaîne
instructions dans votre constructeur Server afin que Claude sache router les réponses via l’outil. Cet exemple indique à Claude de passer chat_id à partir de la balise entrante :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 complet avec outil de réponse
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. 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 demandes de permission
Lorsque Claude appelle un outil qui nécessite une approbation, la boîte de dialogue du terminal local s’ouvre et la session attend. Un canal bidirectionnel peut choisir de recevoir la même demande en parallèle et de vous la relayer sur un autre appareil. Les deux restent actives : vous pouvez répondre dans le terminal ou sur votre téléphone, et Claude Code applique la première réponse reçue et ferme l’autre. Le relais couvre les approbations d’utilisation d’outils commeBash, Write et Edit. Les boîtes de dialogue de confiance accordée au projet et de consentement aux serveurs MCP ne sont pas relayées ; elles n’apparaissent que dans le terminal local.
Claude Code v2.1.234 et versions ultérieures n’envoient les demandes de permission qu’aux serveurs enregistrés comme canaux pour la session, de sorte que le relais est soumis aux mêmes contrôles d’activation par session et d’organisation que la distribution des messages. Le relais exige également que vous activiez le serveur avec --channels ou le flag de développement, et que le serveur déclare la capacité de permission.
Fonctionnement du relais
Lorsqu’une demande de permission s’ouvre, la boucle de relais comporte quatre étapes :- Claude Code génère un court ID de requête et notifie votre serveur
- Votre serveur transmet la demande et l’ID à votre application de chat
- L’utilisateur distant répond par oui ou par non avec cet ID
- Votre gestionnaire entrant analyse la réponse pour en tirer un verdict, et Claude Code ne l’applique que si l’ID correspond à une requête ouverte
Champs de la demande de permission
La notification sortante de Claude Code estnotifications/claude/channel/permission_request. Comme pour la notification de canal, le transport est du MCP standard, mais la méthode et le schéma sont des extensions de Claude Code. L’objet params comporte quatre champs de type chaîne que votre serveur met en forme dans la demande sortante :
Les clients sous Claude Code v2.1.211 ou version ultérieure assainissent
description et input_preview avant de les relayer. Attendez-vous à trois modifications dans le texte que vous recevez :
- Claude Code neutralise les caractères de forçage de direction, les caractères invisibles et les caractères ressemblant à des guillemets et à des chevrons.
- Claude Code réduit chaque suite d’espaces à un seul espace.
- Claude Code relaie le texte en entier jusqu’à 3 500 points de code. Pour une valeur plus longue, vous recevez son début et sa fin autour d’un marqueur comptabilisé
⋯ N code points elided ⋯. La fin d’une commande longue parvient donc toujours à la personne qui approuve.
input_preview, Claude Code applique la limite de 3 500 à chaque champ de premier niveau des arguments séparément et conserve les guillemets structurels propres au JSON. Les clients antérieurs à v2.1.211 relaient description tel quel et coupent input_preview à 200 unités UTF-16 avec des points de suspension à la fin.
Les clients sous Claude Code v2.1.234 ou version ultérieure relaient le marqueur (value unserializable) à la place d’une valeur de champ d’input_preview qu’ils ne peuvent pas sérialiser en toute sécurité, comme une structure circulaire ou un tableau extrêmement volumineux. Vous recevez toujours la clé du champ, et les autres champs de l’aperçu restent inchangés.
Les clients sous Claude Code v2.1.234 ou version ultérieure masquent également les identifiants dans description et input_preview. Vous recevez [REDACTED] à la place d’un jeton d’identification de fournisseur reconnaissable, comme une clé API ou un jeton d’accès personnel. Attendez-vous à trois effets du masquage lorsque vous affichez les champs :
- Claude Code masque les noms de clés dans
input_previewainsi que leurs valeurs. Un nom de clé que vous affichez peut ne pas correspondre au nom de clé dans l’entrée. - Claude Code ne masque jamais un segment contenant une syntaxe shell, des caractères de chemin ou des caractères d’URL. Un masque ne peut pas dissimuler la commande, le chemin de fichier ou la destination en cours d’approbation.
- Claude Code ne masque pas un secret dépourvu de préfixe reconnaissable, ni un secret qui s’étend sur des espaces, comme un bloc de clé privée. Tous deux parviennent à votre serveur sans masquage.
--channels ou le flag de développement. Considérez les deux champs comme non fiables, sauf si vous contrôlez le parc de clients.
Le verdict que votre serveur renvoie est notifications/claude/channel/permission avec deux champs : request_id, qui reprend l’ID ci-dessus, et behavior, défini sur 'allow' ou 'deny'. Allow laisse l’appel d’outil se poursuivre ; deny le rejette. Aucun des deux verdicts n’affecte les appels futurs.
Ajouter le relais à un pont de chat
L’ajout du relais des permissions à un canal bidirectionnel nécessite trois composants :- Une entrée
claude/channel/permission: {}sous les capacitésexperimentaldans votre constructeurServer, afin que Claude Code sache qu’il doit transmettre les demandes - Un gestionnaire de notification pour
notifications/claude/channel/permission_requestqui met en forme la demande et l’envoie via l’API de votre plateforme - Une vérification dans votre gestionnaire de messages entrants qui reconnaît
yes <id>ouno <id>et émet un verdictnotifications/claude/channel/permissionau lieu de transmettre le texte à Claude
1
Déclarer la capacité de permission
Dans votre constructeur
Server, ajoutez claude/channel/permission: {} à côté de claude/channel sous experimental :2
Gérer la requête entrante
Enregistrez un gestionnaire de notification entre votre constructeur
Server et mcp.connect(). Claude Code l’appelle avec les quatre champs de la requête lorsqu’une boîte de dialogue de permission s’ouvre. Votre gestionnaire met en forme la demande pour votre plateforme et inclut des instructions pour répondre avec l’ID :3
Intercepter le verdict dans votre gestionnaire entrant
Votre gestionnaire entrant est la boucle ou le callback qui reçoit les messages de votre plateforme : le même endroit où vous filtrez selon l’expéditeur et émettez
notifications/claude/channel pour transmettre le chat à Claude. Ajoutez, avant l’appel de transmission du chat, une vérification qui reconnaît le format du verdict et émet la notification de permission à la place.L’expression régulière correspond au format d’ID généré par Claude Code : cinq lettres, jamais l. Le flag /i tolère la mise en majuscule de la réponse par la correction automatique du téléphone ; convertissez l’ID capturé en minuscules avant de le renvoyer.- Le format est incorrect : l’expression régulière de votre gestionnaire entrant ne correspond pas, de sorte qu’un texte comme
approve itouyessans ID est transmis à Claude comme un message normal. - L’ID est incorrect : votre serveur émet un verdict, mais Claude Code ne trouve aucune requête ouverte avec cet ID et l’abandonne silencieusement.
- L’ID a été utilisé par une demande précédente : votre serveur émet un verdict avec l’ID de la requête, mais une demande précédente de la session avait le même ID. Dès qu’un ID se répète, Claude Code abandonne tout verdict de canal qui le porte, afin qu’une réponse destinée à une demande ne puisse pas approuver l’autre. Un ID étant composé de cinq lettres aléatoires, une répétition est rare. Répondez plutôt au terminal.
Exemple complet
Le fichierwebhook.ts assemblé ci-dessous combine les trois extensions de cette page : l’outil de réponse, le filtrage des expéditeurs et le relais des permissions. Si vous commencez ici, vous aurez également besoin de la configuration du projet et de l’entrée .mcp.json du guide initial.
Pour que les deux directions puissent être testées avec curl, l’écouteur HTTP sert deux chemins :
GET /events: maintient un flux SSE ouvert et envoie chaque message sortant sous forme de lignedata:, afin quecurl -Npuisse observer en direct l’arrivée des réponses de Claude et des demandes de permission.POST /: le côté entrant, le même gestionnaire que précédemment, avec désormais la vérification du format de verdict insérée avant la branche de transmission du chat.
Full webhook.ts with permission relay
webhook.ts :
Shift+Tab jusqu’à ce que la barre d’état affiche ⏸ manual mode on. En mode auto, le classifieur déciderait de l’appel reply à votre place, et aucune boîte de dialogue ne s’ouvrirait pour que le côté distant y réponde.
Dans le deuxième, diffusez le côté sortant afin de voir les réponses de Claude et les éventuelles demandes de permission au moment où elles se déclenchent :
reply pour renvoyer sa réponse. La boîte de dialogue locale s’ouvre dans votre terminal Claude Code et, un instant plus tard, la demande pour mcp__webhook__reply apparaît dans le flux /events, avec l’ID à cinq lettres. Approuvez-la depuis le côté distant :
reply s’exécute et la réponse de Claude apparaît dans le flux.
Les trois éléments propres aux canaux dans ce fichier :
- Capacités dans le constructeur
Server:claude/channelenregistre l’écouteur de notifications,claude/channel/permissionactive le relais des permissions,toolspermet à Claude de 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 lorsqu’une boîte de dialogue de permission s’ouvre. Tous deux appellentsend()pour diffuser via/events, mais ils sont déclenchés par des parties différentes du système. - Gestionnaire HTTP :
GET /eventsmaintient un flux SSE ouvert afin que curl puisse observer le sortant en direct ;POSTest le côté entrant, filtré selon l’en-têteX-Sender. Un corpsyes <id>ouno <id>est envoyé à Claude Code sous forme de notification de verdict et n’atteint jamais Claude ; tout le reste est transmis à Claude sous forme d’é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. La liste d’approbation par défaut est les plugins de canal dans claude-plugins-official. Le marketplace communautaire n’est pas sur la liste d’approbation des canaux.
Si vous travaillez avec un contact partenaire Anthropic, contactez-le pour coordonner une inscription au marketplace officiel. 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