Channels berada dalam research preview dan memerlukan Claude Code v2.1.80 atau lebih baru. Mereka memerlukan login claude.ai. Autentikasi Console dan API key tidak didukung. Organisasi Team dan Enterprise harus secara eksplisit mengaktifkannya.
- Overview: bagaimana channels bekerja
- Yang Anda butuhkan: persyaratan dan langkah-langkah umum
- Contoh: bangun penerima webhook: panduan satu arah minimal
- Server options: field konstruktor
- Notification format: payload event
- Expose a reply tool: biarkan Claude mengirim pesan kembali
- Gate inbound messages: pemeriksaan pengirim untuk mencegah prompt injection
- Relay permission prompts: teruskan permission prompts ke channels jarak jauh
Overview
Sebuah channel adalah server MCP yang berjalan di mesin yang sama dengan Claude Code. Claude Code menjalankannya sebagai subprocess dan berkomunikasi melalui stdio. Server channel Anda adalah jembatan antara sistem eksternal dan sesi Claude Code:- Chat platforms (Telegram, Discord): plugin Anda berjalan secara lokal dan polling API platform untuk pesan baru. Ketika seseorang DM bot Anda, plugin menerima pesan dan meneruskannya ke Claude. Tidak ada URL untuk diekspos.
- Webhooks (CI, monitoring): server Anda mendengarkan pada port HTTP lokal. Sistem eksternal POST ke port tersebut, dan server Anda mendorong payload ke Claude.
Yang Anda butuhkan
Satu-satunya persyaratan keras adalah paket@modelcontextprotocol/sdk dan runtime yang kompatibel dengan Node.js. Bun, Node, dan Deno semuanya bekerja. Plugin pra-bangun dalam research preview menggunakan Bun, tetapi channel Anda tidak harus.
Server Anda perlu:
- Mendeklarasikan kemampuan
claude/channelsehingga Claude Code mendaftarkan pendengar notifikasi - Memancarkan event
notifications/claude/channelketika sesuatu terjadi - Terhubung melalui stdio transport (Claude Code menjalankan server Anda sebagai subprocess)
--dangerously-load-development-channels untuk menguji secara lokal. Lihat Test during the research preview untuk detail.
Contoh: bangun penerima webhook
Panduan ini membangun server file tunggal yang mendengarkan permintaan HTTP dan meneruskannya ke sesi Claude Code Anda. Pada akhirnya, apa pun yang dapat mengirim HTTP POST, seperti pipeline CI, alert monitoring, atau perintahcurl, dapat mendorong event ke Claude.
Contoh ini menggunakan Bun sebagai runtime untuk server HTTP bawaan dan dukungan TypeScript. Anda dapat menggunakan Node atau Deno sebagai gantinya; satu-satunya persyaratan adalah MCP SDK.
Tulis server channel
Buat file bernama File melakukan tiga hal secara berurutan:
webhook.ts. Ini adalah seluruh server channel Anda: terhubung ke Claude Code melalui stdio, dan mendengarkan POST HTTP pada port 8788. Ketika permintaan tiba, mendorong body ke Claude sebagai channel event.webhook.ts
- Server configuration: membuat server MCP dengan
claude/channeldalam capabilities, yang memberi tahu Claude Code ini adalah channel. Stringinstructionsmasuk ke system prompt Claude: beri tahu Claude event apa yang diharapkan, apakah akan membalas, dan bagaimana cara merutekan balasan jika harus. - Stdio connection: terhubung ke Claude Code melalui stdin/stdout. Ini standar untuk server MCP apa pun: Claude Code menjalankannya sebagai subprocess.
- HTTP listener: memulai server web lokal pada port 8788. Setiap body POST diteruskan ke Claude sebagai channel event melalui
mcp.notification().contentmenjadi body event, dan setiap entrymetamenjadi atribut pada tag<channel>. Pendengar memerlukan akses ke instancemcp, jadi berjalan dalam proses yang sama. Anda dapat membaginya menjadi modul terpisah untuk proyek yang lebih besar.
Daftarkan server Anda dengan Claude Code
Tambahkan server ke konfigurasi MCP Anda sehingga Claude Code tahu cara memulainya. Untuk Claude Code membaca konfigurasi MCP Anda saat startup dan menjalankan setiap server sebagai subprocess.
.mcp.json tingkat proyek di direktori yang sama, gunakan jalur relatif. Untuk konfigurasi tingkat pengguna di ~/.claude.json, gunakan jalur absolut lengkap sehingga server dapat ditemukan dari proyek apa pun:.mcp.json
Uji
Selama research preview, custom channels tidak ada di allowlist, jadi mulai Claude Code dengan flag pengembangan:Ketika Claude Code dimulai, membaca konfigurasi MCP Anda, menjalankan Payload tiba di sesi Claude Code Anda sebagai tag Di terminal Claude Code Anda, Anda akan melihat Claude menerima pesan dan mulai merespons: membaca file, menjalankan perintah, atau apa pun yang diminta pesan. Ini adalah channel satu arah, jadi Claude bertindak dalam sesi Anda tetapi tidak mengirim apa pun kembali melalui webhook. Untuk menambahkan balasan, lihat Expose a reply tool.Jika event tidak tiba, diagnosis tergantung pada apa yang dikembalikan
webhook.ts Anda sebagai subprocess, dan pendengar HTTP dimulai secara otomatis pada port yang Anda konfigurasi (8788 dalam contoh ini). Anda tidak perlu menjalankan server sendiri.Jika Anda melihat “blocked by org policy,” admin Team atau Enterprise Anda perlu mengaktifkan channels terlebih dahulu.Di terminal terpisah, simulasikan webhook dengan mengirim HTTP POST dengan pesan ke server Anda. Contoh ini mengirim alert kegagalan CI ke port 8788 (atau port apa pun yang Anda konfigurasi):<channel>:curl:curlberhasil tetapi tidak ada yang mencapai Claude: jalankan/mcpdalam sesi Anda untuk memeriksa status server. “Failed to connect” biasanya berarti kesalahan dependensi atau impor dalam file server Anda; periksa debug log di~/.claude/debug/<session-id>.txtuntuk jejak stderr.curlgagal dengan “connection refused”: port tidak terikat lagi atau proses basi dari run sebelumnya memegangnya.lsof -i :<port>menunjukkan apa yang mendengarkan;killproses basi sebelum memulai ulang sesi Anda.
Uji selama research preview
Selama research preview, setiap channel harus ada di approved allowlist untuk mendaftar. Flag pengembangan melewati allowlist untuk entri spesifik setelah prompt konfirmasi. Contoh ini menunjukkan kedua tipe entri:--channels tidak memperluas bypass ke entri --channels. Selama research preview, approved allowlist dikurasi oleh Anthropic, jadi channel Anda tetap pada flag pengembangan saat Anda membangun dan menguji.
Flag ini melewati allowlist saja. Kebijakan organisasi
channelsEnabled masih berlaku. Jangan gunakan untuk menjalankan channels dari sumber yang tidak terpercaya.Server options
Sebuah channel menetapkan opsi ini dalam konstruktorServer. Field instructions dan capabilities.tools adalah MCP standar; capabilities.experimental['claude/channel'] dan capabilities.experimental['claude/channel/permission'] adalah penambahan spesifik channel:
| Field | Type | Description |
|---|---|---|
capabilities.experimental['claude/channel'] | object | Diperlukan. Selalu {}. Kehadiran mendaftarkan pendengar notifikasi. |
capabilities.experimental['claude/channel/permission'] | object | Opsional. Selalu {}. Mendeklarasikan bahwa channel ini dapat menerima permission relay requests. Ketika dideklarasikan, Claude Code meneruskan permission prompts ke channel Anda sehingga Anda dapat menyetujui atau menolak mereka dari jarak jauh. Lihat Relay permission prompts. |
capabilities.tools | object | Dua arah saja. Selalu {}. Kemampuan tool MCP standar. Lihat Expose a reply tool. |
instructions | string | Direkomendasikan. Ditambahkan ke system prompt Claude. Beri tahu Claude event apa yang diharapkan, apa arti atribut tag <channel>, apakah akan membalas, dan jika demikian tool mana yang digunakan dan atribut mana yang diteruskan kembali (seperti chat_id). |
capabilities.tools. Contoh ini menunjukkan setup dua arah dengan kemampuan channel, tools, dan instructions yang ditetapkan:
mcp.notification() dengan method notifications/claude/channel. Params ada di bagian berikutnya.
Notification format
Server Anda memancarkannotifications/claude/channel dengan dua params:
| Field | Type | Description |
|---|---|---|
content | string | Body event. Dikirimkan sebagai body dari tag <channel>. |
meta | Record<string, string> | Opsional. Setiap entry menjadi atribut pada tag <channel> untuk konteks routing seperti chat ID, nama pengirim, atau severity alert. Kunci harus identifier: huruf, digit, dan underscore saja. Kunci yang berisi hyphen atau karakter lain secara diam-diam dijatuhkan. |
mcp.notification() pada instance Server. Contoh ini mendorong alert kegagalan CI dengan dua kunci meta:
<channel>. Atribut source ditetapkan secara otomatis dari nama server yang dikonfigurasi:
Expose a reply tool
Jika channel Anda dua arah, seperti chat bridge daripada alert forwarder, ekspos tool MCP standar yang dapat dipanggil Claude untuk mengirim pesan kembali. Tidak ada yang spesifik channel tentang registrasi tool. Tool balasan memiliki tiga komponen:- Entry
tools: {}dalam capabilities konstruktorServerAnda sehingga Claude Code menemukan tool - Tool handlers yang mendefinisikan schema tool dan mengimplementasikan logika pengiriman
- String
instructionsdalam konstruktorServerAnda yang memberi tahu Claude kapan dan bagaimana memanggil tool
Aktifkan penemuan tool
Dalam konstruktor
Server Anda di webhook.ts, tambahkan tools: {} ke capabilities sehingga Claude Code tahu server Anda menawarkan tools:Daftarkan tool balasan
Tambahkan berikut ke
webhook.ts. import masuk di bagian atas file dengan import lainnya; dua handlers masuk antara konstruktor Server dan mcp.connect(). Ini mendaftarkan tool reply yang dapat dipanggil Claude dengan chat_id dan text:webhook.ts lengkap dengan dukungan dua arah. Balasan outbound mengalir melalui GET /events menggunakan Server-Sent Events (SSE), jadi curl -N localhost:8788/events dapat menontonnya secara langsung; chat inbound tiba di POST /:
"Full
Gate inbound messages
Channel tanpa gate adalah vektor prompt injection. Siapa pun yang dapat menjangkau endpoint Anda dapat menempatkan teks di depan Claude. Channel yang mendengarkan platform chat atau endpoint publik memerlukan pemeriksaan pengirim nyata sebelum memancarkan apa pun. Periksa pengirim terhadap allowlist sebelum memanggilmcp.notification(). Contoh ini menjatuhkan pesan apa pun dari pengirim yang tidak ada dalam set:
message.from.id dalam contoh, bukan message.chat.id. Dalam chat grup, ini berbeda, dan gating pada ruangan akan membiarkan siapa pun dalam grup yang diizinkan menyuntikkan pesan ke dalam sesi.
Channel Telegram dan Discord gate pada allowlist pengirim dengan cara yang sama. Mereka bootstrap list dengan pairing: pengguna DM bot, bot membalas dengan kode pairing, pengguna menyetujuinya dalam sesi Claude Code mereka, dan ID platform mereka ditambahkan. Lihat implementasi mana pun untuk alur pairing lengkap. Channel iMessage mengambil pendekatan berbeda: mendeteksi alamat pengguna sendiri dari database Messages saat startup dan membiarkan mereka melewati secara otomatis, dengan pengirim lain ditambahkan oleh handle.
Relay permission prompts
Permission relay memerlukan Claude Code v2.1.81 atau lebih baru. Versi sebelumnya mengabaikan kemampuan
claude/channel/permission.Bash, Write, dan Edit. Dialog kepercayaan proyek dan persetujuan server MCP tidak relay; hanya muncul di terminal lokal.
Bagaimana relay bekerja
Ketika permission prompt terbuka, loop relay memiliki empat langkah:- Claude Code menghasilkan ID permintaan pendek dan memberi tahu server Anda
- Server Anda meneruskan prompt dan ID ke aplikasi chat Anda
- Pengguna jarak jauh membalas dengan ya atau tidak dan ID itu
- Handler inbound Anda menguraikan balasan menjadi verdict, dan Claude Code menerapkannya hanya jika ID cocok dengan permintaan terbuka
Permission request fields
Notifikasi outbound dari Claude Code adalahnotifications/claude/channel/permission_request. Seperti channel notification, transport adalah MCP standar tetapi method dan schema adalah ekstensi Claude Code. Objek params memiliki empat field string yang server Anda format ke dalam prompt outgoing:
| Field | Description |
|---|---|
request_id | Lima huruf kecil diambil dari a-z tanpa l, jadi tidak pernah dibaca sebagai 1 atau I ketika diketik di ponsel. Sertakan dalam prompt outgoing Anda sehingga dapat diulang dalam balasan. Claude Code hanya menerima verdict yang membawa ID yang dikeluarkannya. Dialog terminal lokal tidak menampilkan ID ini, jadi handler outbound Anda adalah satu-satunya cara untuk mempelajarinya. |
tool_name | Nama tool yang ingin dipanggil Claude, misalnya Bash atau Write. |
description | Ringkasan yang dapat dibaca manusia tentang apa yang dilakukan panggilan tool spesifik ini, teks yang sama yang ditampilkan dialog terminal lokal. Untuk panggilan Bash ini adalah deskripsi Claude tentang perintah, atau perintah itu sendiri jika tidak ada yang diberikan. |
input_preview | Argumen tool sebagai string JSON, dipotong menjadi 200 karakter. Untuk Bash ini adalah perintah; untuk Write ini adalah jalur file dan awalan konten. Hilangkan dari prompt Anda jika Anda hanya memiliki ruang untuk pesan satu baris. Server Anda memutuskan apa yang akan ditampilkan. |
notifications/claude/channel/permission dengan dua field: request_id mengulangi ID di atas, dan behavior diatur ke 'allow' atau 'deny'. Allow membiarkan panggilan tool melanjutkan; deny menolaknya, sama seperti menjawab No dalam dialog lokal. Tidak ada verdict yang mempengaruhi panggilan masa depan.
Tambahkan relay ke chat bridge
Menambahkan permission relay ke channel dua arah memerlukan tiga komponen:- Entry
claude/channel/permission: {}di bawah capabilitiesexperimentaldalam konstruktorServerAnda sehingga Claude Code tahu untuk meneruskan prompts - Notification handler untuk
notifications/claude/channel/permission_requestyang memformat prompt dan mengirimnya melalui API platform Anda - Pemeriksaan dalam handler pesan inbound Anda yang mengenali
yes <id>atauno <id>dan memancarkan notifikasinotifications/claude/channel/permissionverdict sebagai gantinya dari meneruskan teks ke Claude
Deklarasikan kemampuan permission
Dalam konstruktor
Server Anda, tambahkan claude/channel/permission: {} bersama claude/channel di bawah experimental:Tangani permintaan masuk
Daftarkan notification handler antara konstruktor
Server Anda dan mcp.connect(). Claude Code memanggilnya dengan empat request fields ketika dialog permission terbuka. Handler Anda memformat prompt untuk platform Anda dan menyertakan instruksi untuk membalas dengan ID:Intersep verdict dalam handler inbound Anda
Handler inbound Anda adalah loop atau callback yang menerima pesan dari platform Anda: tempat yang sama di mana Anda gate pada pengirim dan memancarkan
notifications/claude/channel untuk meneruskan chat ke Claude. Tambahkan pemeriksaan sebelum panggilan chat-forwarding yang mengenali format verdict dan memancarkan notifikasi permission sebagai gantinya.Regex cocok dengan format ID yang dihasilkan Claude Code: lima huruf, tidak pernah l. Flag /i mentoleransi autocorrect ponsel memanfaatkan balasan; hurufkan ID yang ditangkap sebelum mengirimnya kembali.- Format berbeda: regex handler inbound Anda gagal cocok, jadi teks seperti
approve itatauyestanpa ID jatuh melalui sebagai pesan normal ke Claude. - Format benar, ID salah: server Anda memancarkan verdict, tetapi Claude Code tidak menemukan permintaan terbuka dengan ID itu dan menjatuhkannya diam-diam.
Contoh lengkap
webhook.ts yang dirakit di bawah menggabungkan ketiga ekstensi dari halaman ini: tool balasan, sender gating, dan permission relay. Jika Anda memulai di sini, Anda juga akan memerlukan project setup dan entry .mcp.json dari panduan awal.
Untuk membuat kedua arah dapat diuji dari curl, pendengar HTTP melayani dua jalur:
GET /events: memegang aliran SSE terbuka dan mendorong setiap pesan outbound sebagai barisdata:, jadicurl -Ndapat menonton balasan Claude dan permission prompts tiba secara langsung.POST /: sisi inbound, handler yang sama seperti sebelumnya, sekarang dengan pemeriksaan format verdict disisipkan sebelum cabang chat-forward.
"Full
webhook.ts:
/events, termasuk ID lima huruf. Setujui dari sisi jarak jauh:
reply dan mendarat dalam aliran juga.
Tiga bagian spesifik channel dalam file ini:
- Capabilities dalam konstruktor
Server:claude/channelmendaftarkan pendengar notifikasi,claude/channel/permissionopt in ke permission relay,toolsmembiarkan Claude menemukan tool balasan. - Outbound paths: handler tool
replyadalah apa yang dipanggil Claude untuk respons percakapan; handler notifikasiPermissionRequestSchemaadalah apa yang dipanggil Claude Code ketika dialog permission terbuka. Keduanya memanggilsend()untuk broadcast melalui/events, tetapi dipicu oleh bagian berbeda dari sistem. - HTTP handler:
GET /eventsmemegang aliran SSE terbuka sehingga curl dapat menonton outbound secara langsung;POSTadalah inbound, gated pada headerX-Sender. Bodyyes <id>atauno <id>masuk ke Claude Code sebagai notifikasi verdict dan tidak pernah mencapai Claude; apa pun lainnya diteruskan ke Claude sebagai channel event.
Paket sebagai plugin
Untuk membuat channel Anda dapat diinstal dan dibagikan, bungkus dalam plugin dan publikasikan ke marketplace. Pengguna menginstalnya dengan/plugin install, kemudian mengaktifkannya per sesi dengan --channels plugin:<name>@<marketplace>.
Channel yang dipublikasikan ke marketplace Anda sendiri masih memerlukan --dangerously-load-development-channels untuk berjalan, karena tidak ada di approved allowlist. Untuk menambahkannya, kirimkan ke official marketplace. Plugin channel melalui review keamanan sebelum disetujui. Pada rencana Team dan Enterprise, admin dapat sebagai gantinya menyertakan plugin Anda dalam daftar allowedChannelPlugins organisasi, yang menggantikan allowlist Anthropic default.
Lihat juga
- Channels untuk menginstal dan menggunakan Telegram, Discord, iMessage, atau demo fakechat, dan untuk mengaktifkan channels untuk Team atau Enterprise org
- Working channel implementations untuk kode server lengkap dengan alur pairing, tools balasan, dan lampiran file
- MCP untuk protokol dasar yang diimplementasikan server channel
- Plugins untuk mengemas channel Anda sehingga pengguna dapat menginstalnya dengan
/plugin install