Channels befinden sich in Research Preview und erfordern Claude Code v2.1.80 oder später. Sie erfordern eine claude.ai-Anmeldung. Konsolen- und API-Schlüssel-Authentifizierung wird nicht unterstützt. Team- und Enterprise-Organisationen müssen diese explizit aktivieren.
- Übersicht: wie Channels funktionieren
- Was Sie benötigen: Anforderungen und allgemeine Schritte
- Beispiel: Webhook-Empfänger erstellen: eine minimale unidirektionale Anleitung
- Server-Optionen: die Constructor-Felder
- Benachrichtigungsformat: die Event-Payload
- Antwort-Tool bereitstellen: Claude Nachrichten zurücksendet
- Eingehende Nachrichten gaten: Sender-Überprüfungen zur Verhinderung von Prompt-Injection
- Berechtigungsprompts weitergeben: Tool-Genehmigungsprompts an Remote-Channels weiterleiten
Übersicht
Ein Channel ist ein MCP-Server, der auf demselben Computer wie Claude Code ausgeführt wird. Claude Code startet ihn als Unterprozess und kommuniziert über stdio. Ihr Channel-Server ist die Brücke zwischen externen Systemen und der Claude Code-Sitzung:- Chat-Plattformen (Telegram, Discord): Ihr Plugin läuft lokal und fragt die API der Plattform nach neuen Nachrichten ab. Wenn jemand Ihrem Bot eine Direktnachricht sendet, empfängt das Plugin die Nachricht und leitet sie an Claude weiter. Keine URL zum Bereitstellen erforderlich.
- Webhooks (CI, Überwachung): Ihr Server lauscht auf einem lokalen HTTP-Port. Externe Systeme POSTen an diesen Port, und Ihr Server pusht die Payload an Claude.
Was Sie benötigen
Die einzige harte Anforderung ist das@modelcontextprotocol/sdk-Paket und eine Node.js-kompatible Laufzeit. Bun, Node und Deno funktionieren alle. Die vorgefertigten Plugins in der Research Preview verwenden Bun, aber Ihr Channel muss das nicht.
Ihr Server muss:
- Die
claude/channel-Funktionalität deklarieren, damit Claude Code einen Benachrichtigungslistener registriert notifications/claude/channel-Ereignisse emittieren, wenn etwas geschieht- Sich über stdio-Transport verbinden (Claude Code startet Ihren Server als Unterprozess)
--dangerously-load-development-channels zum lokalen Testen. Siehe Testen während der Research Preview für Details.
Beispiel: Webhook-Empfänger erstellen
Diese Anleitung erstellt einen Single-File-Server, der auf HTTP-Anfragen lauscht und diese in Ihre Claude Code-Sitzung weiterleitet. Am Ende kann alles, das einen HTTP POST senden kann, wie eine CI-Pipeline, eine Überwachungsbenachrichtigung oder eincurl-Befehl, Ereignisse an Claude pushen.
Dieses Beispiel verwendet Bun als Laufzeit für seinen integrierten HTTP-Server und TypeScript-Unterstützung. Sie können stattdessen Node oder Deno verwenden; die einzige Anforderung ist das MCP SDK.
Schreiben Sie den Channel-Server
Erstellen Sie eine Datei namens Die Datei macht drei Dinge in Reihenfolge:
webhook.ts. Dies ist Ihr gesamter Channel-Server: Er verbindet sich mit Claude Code über stdio und lauscht auf HTTP POSTs auf Port 8788. Wenn eine Anfrage ankommt, pusht er den Body als Channel-Ereignis an Claude.webhook.ts
- Server-Konfiguration: erstellt den MCP-Server mit
claude/channelin seinen Funktionalitäten, was Claude Code mitteilt, dass dies ein Channel ist. Dieinstructions-Zeichenkette geht in Claudes System-Prompt: teilen Sie Claude mit, welche Ereignisse zu erwarten sind, ob es antworten soll, und wie Antworten weitergeleitet werden sollen, falls ja. - Stdio-Verbindung: verbindet sich mit Claude Code über stdin/stdout. Dies ist Standard für jeden MCP-Server: Claude Code startet ihn als Unterprozess.
- HTTP-Listener: startet einen lokalen Webserver auf Port 8788. Jeder POST-Body wird über
mcp.notification()als Channel-Ereignis an Claude weitergeleitet. Dercontentwird zum Event-Body, und jedermeta-Eintrag wird zu einem Attribut auf dem<channel>-Tag. Der Listener benötigt Zugriff auf diemcp-Instanz, daher läuft er im selben Prozess. Sie könnten ihn für ein größeres Projekt in separate Module aufteilen.
Registrieren Sie Ihren Server bei Claude Code
Fügen Sie den Server zu Ihrer MCP-Konfiguration hinzu, damit Claude Code weiß, wie er zu starten ist. Für eine Projekt-Level Claude Code liest Ihre MCP-Konfiguration beim Start und startet jeden Server als Unterprozess.
.mcp.json im selben Verzeichnis verwenden Sie einen relativen Pfad. Für Benutzer-Level-Konfiguration in ~/.claude.json verwenden Sie den vollständigen absoluten Pfad, damit der Server von jedem Projekt aus gefunden werden kann:.mcp.json
Testen Sie es
Während der Research Preview befinden sich benutzerdefinierte Channels nicht auf der Allowlist, daher starten Sie Claude Code mit dem Development-Flag:Wenn Claude Code startet, liest es Ihre MCP-Konfiguration, startet Ihre Die Payload kommt in Ihrer Claude Code-Sitzung als In Ihrem Claude Code-Terminal sehen Sie, dass Claude die Nachricht empfängt und anfängt zu antworten: Dateien lesen, Befehle ausführen oder was auch immer die Nachricht erfordert. Dies ist ein unidirektionaler Channel, daher handelt Claude in Ihrer Sitzung, sendet aber nichts über den Webhook zurück. Um Antworten hinzuzufügen, siehe Antwort-Tool bereitstellen.Wenn das Ereignis nicht ankommt, hängt die Diagnose davon ab, was
webhook.ts als Unterprozess, und der HTTP-Listener startet automatisch auf dem konfigurierten Port (8788 in diesem Beispiel). Sie müssen den Server nicht selbst ausführen.Wenn Sie “blocked by org policy” sehen, muss Ihr Team- oder Enterprise-Admin Channels aktivieren zuerst.Simulieren Sie in einem separaten Terminal einen Webhook, indem Sie einen HTTP POST mit einer Nachricht an Ihren Server senden. Dieses Beispiel sendet eine CI-Fehlerbenachrichtigung an Port 8788 (oder welchen Port Sie konfiguriert haben):<channel>-Tag an:curl zurückgegeben hat:curlerfolgreich, aber nichts erreicht Claude: führen Sie/mcpin Ihrer Sitzung aus, um den Status des Servers zu überprüfen. “Failed to connect” bedeutet normalerweise einen Abhängigkeits- oder Importfehler in Ihrer Serverdatei; überprüfen Sie das Debug-Log unter~/.claude/debug/<session-id>.txtfür die stderr-Spur.curlschlägt mit “connection refused” fehl: der Port ist entweder noch nicht gebunden oder ein veralteter Prozess aus einem früheren Lauf hält ihn.lsof -i :<port>zeigt, was lauscht;killden veralteten Prozess, bevor Sie Ihre Sitzung neu starten.
Testen während der Research Preview
Während der Research Preview muss sich jeder Channel auf der genehmigten Allowlist befinden, um sich zu registrieren. Das Development-Flag umgeht die Allowlist für spezifische Einträge nach einer Bestätigungsaufforderung. Dieses Beispiel zeigt beide Eintragstypen:--channels erweitert den Bypass nicht auf die --channels-Einträge. Während der Research Preview ist die genehmigte Allowlist von Anthropic kuratiert, daher bleibt Ihr Channel auf dem Development-Flag, während Sie ihn erstellen und testen.
Dieses Flag überspringt nur die Allowlist. Die
channelsEnabled-Organisationsrichtlinie gilt weiterhin. Verwenden Sie es nicht, um Channels aus nicht vertrauenswürdigen Quellen auszuführen.Server-Optionen
Ein Channel setzt diese Optionen imServer-Constructor. Die Felder instructions und capabilities.tools sind Standard-MCP; capabilities.experimental['claude/channel'] und capabilities.experimental['claude/channel/permission'] sind die Channel-spezifischen Ergänzungen:
| Feld | Typ | Beschreibung |
|---|---|---|
capabilities.experimental['claude/channel'] | object | Erforderlich. Immer {}. Das Vorhandensein registriert den Benachrichtigungslistener. |
capabilities.experimental['claude/channel/permission'] | object | Optional. Immer {}. Deklariert, dass dieser Channel Berechtigungsweitergabeanfragen empfangen kann. Wenn deklariert, leitet Claude Code Tool-Genehmigungsprompts an Ihren Channel weiter, damit Sie diese remote genehmigen oder ablehnen können. Siehe Berechtigungsprompts weitergeben. |
capabilities.tools | object | Nur bidirektional. Immer {}. Standard-MCP-Tool-Funktionalität. Siehe Antwort-Tool bereitstellen. |
instructions | string | Empfohlen. Hinzugefügt zu Claudes System-Prompt. Teilen Sie Claude mit, welche Ereignisse zu erwarten sind, was die <channel>-Tag-Attribute bedeuten, ob es antworten soll, und wenn ja, welches Tool zu verwenden ist und welches Attribut zurückzugeben ist (wie chat_id). |
capabilities.tools weg. Dieses Beispiel zeigt ein bidirektionales Setup mit der Channel-Funktionalität, Tools und Anweisungen:
mcp.notification() mit der Methode notifications/claude/channel auf. Die Parameter sind im nächsten Abschnitt.
Benachrichtigungsformat
Ihr Server emittiertnotifications/claude/channel mit zwei Parametern:
| Feld | Typ | Beschreibung |
|---|---|---|
content | string | Der Event-Body. Wird als Body des <channel>-Tags bereitgestellt. |
meta | Record<string, string> | Optional. Jeder Eintrag wird zu einem Attribut auf dem <channel>-Tag für Routing-Kontext wie Chat-ID, Sendername oder Benachrichtigungsschweregrad. Schlüssel müssen Bezeichner sein: nur Buchstaben, Ziffern und Unterstriche. Schlüssel mit Bindestrichen oder anderen Zeichen werden stillschweigend gelöscht. |
mcp.notification() auf der Server-Instanz. Dieses Beispiel pusht eine CI-Fehlerbenachrichtigung mit zwei Meta-Schlüsseln:
<channel>-Tag an. Das source-Attribut wird automatisch aus dem konfigurierten Namen Ihres Servers gesetzt:
Antwort-Tool bereitstellen
Wenn Ihr Channel bidirektional ist, wie eine Chat-Brücke statt eines Alert-Forwarders, stellen Sie ein Standard-MCP-Tool zur Verfügung, das Claude aufrufen kann, um Nachrichten zurückzusenden. Nichts an der Tool-Registrierung ist Channel-spezifisch. Ein Antwort-Tool hat drei Komponenten:- Ein
tools: {}-Eintrag in IhrenServer-Constructor-Funktionalitäten, damit Claude Code das Tool entdeckt - Tool-Handler, die das Tool-Schema definieren und die Versendungslogik implementieren
- Eine
instructions-Zeichenkette in IhremServer-Constructor, die Claude mitteilt, wann und wie das Tool aufgerufen wird
Aktivieren Sie die Tool-Entdeckung
In Ihrem
Server-Constructor in webhook.ts fügen Sie tools: {} zu den Funktionalitäten hinzu, damit Claude Code weiß, dass Ihr Server Tools anbietet:Registrieren Sie das Antwort-Tool
Fügen Sie Folgendes zu
webhook.ts hinzu. Der import geht oben in der Datei mit Ihren anderen Importen; die zwei Handler gehen zwischen dem Server-Constructor und mcp.connect(). Dies registriert ein reply-Tool, das Claude mit einer chat_id und text aufrufen kann:webhook.ts mit bidirektionaler Unterstützung. Ausgehende Antworten streamen über GET /events mit Server-Sent Events (SSE), daher kann curl -N localhost:8788/events sie live beobachten; eingehender Chat kommt auf POST / an:
"Full
Eingehende Nachrichten gaten
Ein ungegatterter Channel ist ein Prompt-Injection-Vektor. Jeder, der Ihren Endpunkt erreichen kann, kann Text vor Claude platzieren. Ein Channel, der auf einer Chat-Plattform oder einem öffentlichen Endpunkt lauscht, benötigt eine echte Sender-Überprüfung, bevor er etwas emittiert. Überprüfen Sie den Sender gegen eine Allowlist, bevor Siemcp.notification() aufrufen. Dieses Beispiel löscht jede Nachricht von einem Sender, der nicht in der Menge ist:
message.from.id im Beispiel, nicht message.chat.id. In Gruppenchats unterscheiden sich diese, und das Gaten auf dem Raum würde jedem in einer genehmigten Gruppe erlauben, Nachrichten in die Sitzung einzuspritzen.
Die Telegram- und Discord-Channels gaten auf die gleiche Weise auf einer Sender-Allowlist. Sie bootstrappen die Liste durch Pairing: Der Benutzer sendet dem Bot eine Direktnachricht, der Bot antwortet mit einem Pairing-Code, der Benutzer genehmigt ihn in seiner Claude Code-Sitzung, und seine Plattform-ID wird hinzugefügt. Siehe eine der Implementierungen für den vollständigen Pairing-Flow. Der iMessage-Channel verfolgt einen anderen Ansatz: Er erkennt die eigenen Adressen des Benutzers aus der Messages-Datenbank beim Start und lässt sie automatisch durch, wobei andere Sender nach Handle hinzugefügt werden.
Berechtigungsprompts weitergeben
Die Berechtigungsweitergabe erfordert Claude Code v2.1.81 oder später. Frühere Versionen ignorieren die
claude/channel/permission-Funktionalität.Wie die Weitergabe funktioniert
Wenn ein Berechtigungsprompt öffnet, hat die Weitergabeschleife vier Schritte:- Claude Code generiert eine kurze Request-ID und benachrichtigt Ihren Server
- Ihr Server leitet den Prompt und die ID an Ihre Chat-App weiter
- Der Remote-Benutzer antwortet mit ja oder nein und dieser ID
- Ihr eingehender Handler analysiert die Antwort in ein Urteil, und Claude Code wendet es nur an, wenn die ID einer offenen Anfrage entspricht
Berechtigungsanfrage-Felder
Die ausgehende Benachrichtigung von Claude Code istnotifications/claude/channel/permission_request. Wie die Channel-Benachrichtigung ist der Transport Standard-MCP, aber die Methode und das Schema sind Claude Code-Erweiterungen. Das params-Objekt hat vier String-Felder, die Ihr Server in den ausgehenden Prompt formatiert:
| Feld | Beschreibung |
|---|---|
request_id | Fünf Kleinbuchstaben aus a-z ohne l, damit es nie als 1 oder I gelesen wird, wenn es auf einem Telefon eingegeben wird. Fügen Sie es in Ihren ausgehenden Prompt ein, damit es in der Antwort wiederholt werden kann. Claude Code akzeptiert nur ein Urteil, das eine ID trägt, die es ausgestellt hat. Der lokale Terminal-Dialog zeigt diese ID nicht an, daher ist Ihr ausgehender Handler die einzige Möglichkeit, sie zu erfahren. |
tool_name | Name des Tools, das Claude verwenden möchte, zum Beispiel Bash oder Write. |
description | Menschenlesbarer Zusammenfassung dessen, was dieser spezifische Tool-Aufruf tut, derselbe Text, den der lokale Terminal-Dialog zeigt. Für einen Bash-Aufruf ist dies Claudes Beschreibung des Befehls oder der Befehl selbst, wenn keine gegeben wurde. |
input_preview | Die Argumente des Tools als JSON-Zeichenkette, gekürzt auf 200 Zeichen. Für Bash ist dies der Befehl; für Write ist es der Dateipfad und ein Präfix des Inhalts. Lassen Sie es aus Ihrem Prompt weg, wenn Sie nur Platz für eine einzeilige Nachricht haben. Ihr Server entscheidet, was angezeigt wird. |
notifications/claude/channel/permission mit zwei Feldern: request_id, das die obige ID wiederholt, und behavior, das auf 'allow' oder 'deny' gesetzt ist. Allow lässt den Tool-Aufruf fortfahren; deny lehnt ihn ab, dasselbe wie das Antworten mit Nein im lokalen Dialog. Weder das Urteil beeinflusst zukünftige Aufrufe.
Weitergabe zu einer Chat-Brücke hinzufügen
Das Hinzufügen von Berechtigungsweitergabe zu einem bidirektionalen Channel erfordert drei Komponenten:- Ein
claude/channel/permission: {}-Eintrag unterexperimental-Funktionalitäten in IhremServer-Constructor, damit Claude Code weiß, dass Prompts weitergeleitet werden sollen - Ein Benachrichtigungshandler für
notifications/claude/channel/permission_request, der den Prompt formatiert und ihn über Ihre Plattform-API sendet - Eine Überprüfung in Ihrem eingehenden Nachrichtenhandler, die
yes <id>oderno <id>erkennt und stattdessen einenotifications/claude/channel/permission-Urteilsbenachrichtigung emittiert, anstatt den Text an Claude weiterzuleiten
Deklarieren Sie die Berechtigungsfunktionalität
In Ihrem
Server-Constructor fügen Sie claude/channel/permission: {} neben claude/channel unter experimental hinzu:Behandeln Sie die eingehende Anfrage
Registrieren Sie einen Benachrichtigungshandler zwischen Ihrem
Server-Constructor und mcp.connect(). Claude Code ruft ihn mit den vier Anfrage-Feldern auf, wenn ein Berechtigungsdialog öffnet. Ihr Handler formatiert den Prompt für Ihre Plattform und enthält Anweisungen zum Antworten mit der ID:Fangen Sie das Urteil in Ihrem eingehenden Handler ab
Ihr eingehender Handler ist die Schleife oder der Callback, der Nachrichten von Ihrer Plattform empfängt: derselbe Ort, an dem Sie auf Sender gaten und
notifications/claude/channel emittieren, um Chat an Claude weiterzuleiten. Fügen Sie eine Überprüfung vor dem Chat-Weiterleitungsaufruf hinzu, die das Urteilsformat erkennt und stattdessen die Berechtigungsbenachrichtigung emittiert.Der Regex entspricht dem ID-Format, das Claude Code generiert: fünf Buchstaben, nie l. Das /i-Flag toleriert Telefon-Autokorrektur, die die Antwort großschreibt; kleinschreiben Sie die erfasste ID, bevor Sie sie zurücksendet.- Anderes Format: der Regex Ihres eingehenden Handlers schlägt fehl zu entsprechen, daher fällt Text wie
approve itoderyesohne ID als normale Nachricht an Claude durch. - Richtiges Format, falsche ID: Ihr Server emittiert ein Urteil, aber Claude Code findet keine offene Anfrage mit dieser ID und löscht es stillschweigend.
Vollständiges Beispiel
Die zusammengestelltewebhook.ts unten kombiniert alle drei Erweiterungen von dieser Seite: das Antwort-Tool, Sender-Gating und Berechtigungsweitergabe. Wenn Sie hier anfangen, benötigen Sie auch die Projekt-Setup und .mcp.json-Eintrag aus der anfänglichen Anleitung.
Um beide Richtungen von curl aus testbar zu machen, dient der HTTP-Listener zwei Pfaden:
GET /events: hält einen SSE-Stream offen und pusht jede ausgehende Nachricht alsdata:-Zeile, daher kanncurl -NClaudes Antworten und Berechtigungsprompts live beobachten, wenn sie ankommen.POST /: die eingehende Seite, derselbe Handler wie zuvor, jetzt mit der Urteilsformat-Überprüfung vor dem Chat-Weiterleitungszweig eingefügt.
"Full
webhook.ts startet:
/events-Stream, einschließlich der fünf-buchstabigen ID. Genehmigen Sie ihn von der Remote-Seite:
reply-Tool zurück und landet auch im Stream.
Die drei Channel-spezifischen Teile in dieser Datei:
- Funktionalitäten im
Server-Constructor:claude/channelregistriert den Benachrichtigungslistener,claude/channel/permissionentscheidet sich für Berechtigungsweitergabe,toolslässt Claude das Antwort-Tool entdecken. - Ausgehende Pfade: der
reply-Tool-Handler ist das, was Claude für Gesprächsantworten aufruft; derPermissionRequestSchema-Benachrichtigungshandler ist das, was Claude Code aufruft, wenn ein Berechtigungsdialog öffnet. Beide rufensend()auf, um über/eventszu übertragen, aber sie werden von verschiedenen Teilen des Systems ausgelöst. - HTTP-Handler:
GET /eventshält einen SSE-Stream offen, damit curl Ausgangsrichtung live beobachten kann;POSTist eingehend, gatet auf demX-Sender-Header. Einyes <id>- oderno <id>-Body geht an Claude Code als Urteilsbenachrichtigung und erreicht nie Claude; alles andere wird an Claude als Channel-Ereignis weitergeleitet.
Als Plugin verpacken
Um Ihren Channel installierbar und teilbar zu machen, wickeln Sie ihn in ein Plugin ein und veröffentlichen Sie ihn auf einem Marketplace. Benutzer installieren ihn mit/plugin install, dann aktivieren ihn pro Sitzung mit --channels plugin:<name>@<marketplace>.
Ein Channel, der auf Ihrem eigenen Marketplace veröffentlicht wird, benötigt immer noch --dangerously-load-development-channels zum Ausführen, da er nicht auf der genehmigten Allowlist ist. Um ihn hinzufügen zu lassen, reichen Sie ihn beim offiziellen Marketplace ein. Channel-Plugins durchlaufen eine Sicherheitsüberprüfung, bevor sie genehmigt werden. Bei Team- und Enterprise-Plänen kann ein Admin stattdessen Ihr Plugin in die allowedChannelPlugins-Liste der Organisation aufnehmen, die die Standard-Anthropic-Allowlist ersetzt.
Siehe auch
- Channels zum Installieren und Verwenden von Telegram, Discord, iMessage oder der fakechat-Demo und zum Aktivieren von Channels für eine Team- oder Enterprise-Organisation
- Arbeitende Channel-Implementierungen für vollständigen Server-Code mit Pairing-Flows, Antwort-Tools und Dateianhängen
- MCP für das zugrunde liegende Protokoll, das Channel-Server implementieren
- Plugins zum Verpacken Ihres Channels, damit Benutzer ihn mit
/plugin installinstallieren können