Каналы находятся в исследовательском превью и требуют Claude Code v2.1.80 или более поздней версии. Они требуют входа claude.ai. Аутентификация через консоль и ключ API не поддерживается. Организации Team и Enterprise должны явно их включить.
- Обзор: как работают каналы
- Что вам нужно: требования и общие шаги
- Пример: создание приёмника вебхуков: минимальное пошаговое руководство в одну сторону
- Параметры сервера: поля конструктора
- Формат уведомления: полезная нагрузка события
- Предоставление инструмента ответа: позволить Claude отправлять сообщения обратно
- Проверка входящих сообщений: проверки отправителя для предотвращения инъекции подсказок
- Трансляция запросов разрешений: пересылка запросов одобрения инструментов на удалённые каналы
Обзор
Канал — это MCP сервер, который работает на той же машине, что и Claude Code. Claude Code запускает его как подпроцесс и взаимодействует через stdio. Ваш сервер канала — это мост между внешними системами и сеансом Claude Code:- Платформы чата (Telegram, Discord): ваш плагин работает локально и опрашивает API платформы на предмет новых сообщений. Когда кто-то отправляет личное сообщение вашему боту, плагин получает сообщение и пересылает его Claude. Нет необходимости в URL для открытия.
- Вебхуки (CI, мониторинг): ваш сервер прослушивает локальный HTTP-порт. Внешние системы отправляют POST на этот порт, и ваш сервер отправляет полезную нагрузку Claude.
Что вам нужно
Единственное жёсткое требование — это пакет@modelcontextprotocol/sdk и совместимая с Node.js среда выполнения. Bun, Node и Deno работают. Предварительно созданные плагины в исследовательском превью используют Bun, но ваш канал не обязательно должен.
Ваш сервер должен:
- Объявить возможность
claude/channel, чтобы Claude Code зарегистрировал слушатель уведомлений - Отправлять события
notifications/claude/channelпри возникновении чего-либо - Подключаться через транспорт stdio (Claude Code запускает ваш сервер как подпроцесс)
--dangerously-load-development-channels для локального тестирования. Подробности см. в Тестирование во время исследовательского превью.
Пример: создание приёмника вебхуков
Это пошаговое руководство создаёт однофайловый сервер, который прослушивает HTTP-запросы и пересылает их в ваш сеанс Claude Code. В конце концов, всё, что может отправить HTTP POST, например конвейер CI, оповещение мониторинга или командаcurl, может отправлять события Claude.
В этом примере используется Bun в качестве среды выполнения благодаря встроенному HTTP-серверу и поддержке TypeScript. Вы можете использовать Node или Deno; единственное требование — это MCP SDK.
Написание сервера канала
Создайте файл с именем Файл делает три вещи по порядку:
webhook.ts. Это ваш полный сервер канала: он подключается к Claude Code через stdio и прослушивает HTTP POST на порту 8788. Когда приходит запрос, он отправляет тело Claude как событие канала.webhook.ts
- Конфигурация сервера: создаёт MCP-сервер с
claude/channelв его возможностях, что говорит Claude Code, что это канал. Строкаinstructionsпереходит в системную подсказку Claude: скажите Claude, какие события ожидать, нужно ли отвечать и как маршрутизировать ответы, если нужно. - Подключение stdio: подключается к Claude Code через stdin/stdout. Это стандартно для любого MCP-сервера: Claude Code запускает его как подпроцесс.
- Слушатель HTTP: запускает локальный веб-сервер на порту 8788. Каждое тело POST пересылается Claude как событие канала через
mcp.notification().contentстановится телом события, а каждая записьmetaстановится атрибутом на теге<channel>. Слушателю нужен доступ к экземпляруmcp, поэтому он работает в том же процессе. Вы можете разделить его на отдельные модули для более крупного проекта.
Регистрация вашего сервера с Claude Code
Добавьте сервер в вашу конфигурацию MCP, чтобы Claude Code знал, как его запустить. Для проекта Claude Code читает вашу конфигурацию MCP при запуске и запускает каждый сервер как подпроцесс.
.mcp.json в том же каталоге используйте относительный путь. Для конфигурации уровня пользователя в ~/.claude.json используйте полный абсолютный путь, чтобы сервер можно было найти из любого проекта:.mcp.json
Тестирование
Во время исследовательского превью пользовательские каналы не находятся в списке разрешений, поэтому запустите Claude Code с флагом разработки:Когда Claude Code запускается, он читает вашу конфигурацию MCP, запускает ваш Полезная нагрузка поступает в ваш сеанс Claude Code как тег В вашем терминале Claude Code вы увидите, как Claude получает сообщение и начинает отвечать: чтение файлов, выполнение команд или всё, что требует сообщение. Это односторонний канал, поэтому Claude действует в вашем сеансе, но ничего не отправляет обратно через вебхук. Чтобы добавить ответы, см. Предоставление инструмента ответа.Если событие не поступает, диагностика зависит от того, что вернул
webhook.ts как подпроцесс, и слушатель HTTP автоматически запускается на настроенном вами порту (8788 в этом примере). Вам не нужно запускать сервер самостоятельно.Если вы видите “blocked by org policy”, ваш администратор Team или Enterprise должен сначала включить каналы.В отдельном терминале имитируйте вебхук, отправив HTTP POST с сообщением на ваш сервер. Этот пример отправляет оповещение об ошибке CI на порт 8788 (или любой другой настроенный вами порт):<channel>:curl:curlуспешен, но ничего не достигает Claude: запустите/mcpв вашем сеансе, чтобы проверить статус сервера. “Failed to connect” обычно означает ошибку зависимости или импорта в файле вашего сервера; проверьте журнал отладки в~/.claude/debug/<session-id>.txtдля трассировки stderr.curlне удаётся с “connection refused”: порт либо ещё не привязан, либо устаревший процесс из более раннего запуска его удерживает.lsof -i :<port>показывает, что прослушивается;killустаревший процесс перед перезагрузкой вашего сеанса.
Тестирование во время исследовательского превью
Во время исследовательского превью каждый канал должен быть в одобренном списке разрешений для регистрации. Флаг разработки обходит список разрешений для конкретных записей после подтверждающего запроса. Этот пример показывает оба типа записей:--channels не распространяет обход на записи --channels. Во время исследовательского превью одобренный список разрешений курируется Anthropic, поэтому ваш канал остаётся на флаге разработки во время разработки и тестирования.
Этот флаг пропускает только список разрешений. Политика организации
channelsEnabled по-прежнему применяется. Не используйте его для запуска каналов из ненадёжных источников.Параметры сервера
Канал устанавливает эти параметры в конструктореServer. Поля instructions и capabilities.tools являются стандартным MCP; capabilities.experimental['claude/channel'] и capabilities.experimental['claude/channel/permission'] — это дополнения, специфичные для канала:
| Поле | Тип | Описание |
|---|---|---|
capabilities.experimental['claude/channel'] | object | Обязательно. Всегда {}. Наличие регистрирует слушатель уведомлений. |
capabilities.experimental['claude/channel/permission'] | object | Опционально. Всегда {}. Объявляет, что этот канал может получать запросы трансляции разрешений. При объявлении Claude Code пересылает запросы одобрения инструментов на ваш канал, чтобы вы могли одобрять или отклонять их удалённо. См. Трансляция запросов разрешений. |
capabilities.tools | object | Только двусторонний. Всегда {}. Стандартная возможность инструмента MCP. См. Предоставление инструмента ответа. |
instructions | string | Рекомендуется. Добавляется в системную подсказку Claude. Скажите Claude, какие события ожидать, что означают атрибуты тега <channel>, нужно ли отвечать и если да, какой инструмент использовать и какой атрибут передать обратно (например chat_id). |
capabilities.tools. Этот пример показывает двустороннюю установку с объявленными возможностью канала, инструментами и инструкциями:
mcp.notification() с методом notifications/claude/channel. Параметры находятся в следующем разделе.
Формат уведомления
Ваш сервер отправляетnotifications/claude/channel с двумя параметрами:
| Поле | Тип | Описание |
|---|---|---|
content | string | Тело события. Доставляется как тело тега <channel>. |
meta | Record<string, string> | Опционально. Каждая запись становится атрибутом на теге <channel> для контекста маршрутизации, такого как ID чата, имя отправителя или серьёзность оповещения. Ключи должны быть идентификаторами: только буквы, цифры и подчёркивания. Ключи, содержащие дефисы или другие символы, молча отбрасываются. |
mcp.notification() на экземпляре Server. Этот пример отправляет оповещение об ошибке CI с двумя ключами meta:
<channel>. Атрибут source устанавливается автоматически из имени вашего сервера:
Предоставление инструмента ответа
Если ваш канал двусторонний, например мост чата, а не пересылка оповещений, предоставьте стандартный инструмент MCP, который Claude может вызвать для отправки сообщений обратно. Ничего в регистрации инструмента не является специфичным для канала. Инструмент ответа имеет три компонента:- Запись
tools: {}в возможностях конструктораServer, чтобы Claude Code обнаружил инструмент - Обработчики инструментов, которые определяют схему инструмента и реализуют логику отправки
- Строка
instructionsв конструктореServer, которая говорит Claude, когда и как вызывать инструмент
Включение обнаружения инструментов
В конструкторе
Server в webhook.ts добавьте tools: {} в возможности, чтобы Claude Code знал, что ваш сервер предлагает инструменты:Регистрация инструмента ответа
Добавьте следующее в
webhook.ts. import переходит в верхнюю часть файла с вашими другими импортами; два обработчика переходят между конструктором Server и mcp.connect(). Это регистрирует инструмент reply, который Claude может вызвать с chat_id и text:webhook.ts с двусторонней поддержкой. Исходящие ответы передаются через GET /events с использованием Server-Sent Events (SSE), поэтому curl -N localhost:8788/events может смотреть их в реальном времени; входящий чат поступает на POST /:
"Full
Проверка входящих сообщений
Непроверенный канал — это вектор инъекции подсказок. Любой, кто может достичь вашей конечной точки, может поместить текст перед Claude. Канал, прослушивающий платформу чата или общедоступную конечную точку, нуждается в реальной проверке отправителя перед отправкой чего-либо. Проверьте отправителя против списка разрешений перед вызовомmcp.notification(). Этот пример отбрасывает любое сообщение от отправителя, не входящего в набор:
message.from.id в примере, а не message.chat.id. В групповых чатах они отличаются, и проверка по комнате позволила бы любому в разрешённой группе вводить сообщения в сеанс.
Каналы Telegram и Discord проверяют список разрешений отправителя так же. Они загружают список путём спаривания: пользователь отправляет личное сообщение боту, бот отвечает кодом спаривания, пользователь одобряет его в своём сеансе Claude Code, и его ID платформы добавляется. Полный поток спаривания см. в любой реализации. Канал iMessage использует другой подход: он обнаруживает собственные адреса пользователя из базы данных Messages при запуске и пропускает их автоматически, с другими отправителями, добавляемыми по дескриптору.
Трансляция запросов разрешений
Трансляция разрешений требует Claude Code v2.1.81 или более поздней версии. Более ранние версии игнорируют возможность
claude/channel/permission.Bash, Write и Edit. Диалоги доверия проекта и согласия MCP-сервера не передаются; они появляются только в локальном терминале.
Как работает трансляция
Когда открывается запрос разрешения, цикл трансляции имеет четыре шага:- Claude Code генерирует короткий ID запроса и уведомляет ваш сервер
- Ваш сервер пересылает запрос и ID в ваше приложение чата
- Удалённый пользователь отвечает да или нет и этот ID
- Ваш входящий обработчик анализирует ответ в вердикт, и Claude Code применяет его только если ID совпадает с открытым запросом
Поля запроса разрешения
Исходящее уведомление от Claude Code — этоnotifications/claude/channel/permission_request. Как и уведомление канала, транспорт — это стандартный MCP, но метод и схема — это расширения Claude Code. Объект params имеет четыре строковых поля, которые ваш сервер форматирует в исходящий запрос:
| Поле | Описание |
|---|---|
request_id | Пять строчных букв, взятых из a-z без l, поэтому это никогда не читается как 1 или I при вводе на телефоне. Включите его в ваш исходящий запрос, чтобы его можно было повторить в ответе. Claude Code принимает только вердикт, который несёт ID, который он выдал. Диалог локального терминала не отображает этот ID, поэтому ваш исходящий обработчик — единственный способ узнать его. |
tool_name | Имя инструмента, который Claude хочет использовать, например Bash или Write. |
description | Понятное человеку резюме того, что делает этот конкретный вызов инструмента, тот же текст, который показывает диалог локального терминала. Для вызова Bash это описание Claude команды или сама команда, если описание не было дано. |
input_preview | Аргументы инструмента как строка JSON, усечённая до 200 символов. Для Bash это команда; для Write это путь файла и префикс содержимого. Опустите его из вашего запроса, если у вас есть место только для однострочного сообщения. Ваш сервер решает, что показать. |
notifications/claude/channel/permission с двумя полями: request_id, повторяющий ID выше, и behavior, установленный на 'allow' или 'deny'. Allow позволяет вызову инструмента продолжиться; deny отклоняет его, то же самое, что ответить No в локальном диалоге. Ни один вердикт не влияет на будущие вызовы.
Добавление трансляции к мосту чата
Добавление трансляции разрешений к двустороннему каналу требует трёх компонентов:- Запись
claude/channel/permission: {}подexperimentalвозможностями в конструктореServer, чтобы Claude Code знал пересылать запросы - Обработчик уведомлений для
notifications/claude/channel/permission_request, который форматирует запрос и отправляет его через API вашей платформы - Проверка в вашем входящем обработчике сообщений, которая распознаёт
yes <id>илиno <id>и отправляет уведомление вердиктаnotifications/claude/channel/permissionвместо пересылки текста Claude
Объявление возможности разрешения
В конструкторе
Server добавьте claude/channel/permission: {} рядом с claude/channel под experimental:Обработка входящего запроса
Зарегистрируйте обработчик уведомлений между конструктором
Server и mcp.connect(). Claude Code вызывает его с четырьмя полями запроса при открытии диалога разрешения. Ваш обработчик форматирует запрос для вашей платформы и включает инструкции для ответа с ID:Перехват вердикта в вашем входящем обработчике
Ваш входящий обработчик — это цикл или обратный вызов, который получает сообщения от вашей платформы: то же место, где вы проверяете отправителя и отправляете
notifications/claude/channel для пересылки чата Claude. Добавьте проверку перед вызовом пересылки чата, которая распознаёт формат вердикта и отправляет уведомление разрешения вместо этого.Регулярное выражение совпадает с форматом ID, который генерирует Claude Code: пять букв, никогда l. Флаг /i допускает автокоррекцию телефона, капитализирующую ответ; приведите захваченный ID в нижний регистр перед отправкой обратно.- Другой формат: регулярное выражение вашего входящего обработчика не совпадает, поэтому текст, такой как
approve itилиyesбез ID, переходит как обычное сообщение Claude. - Правильный формат, неправильный ID: ваш сервер отправляет вердикт, но Claude Code не находит открытый запрос с этим ID и молча его отбрасывает.
Полный пример
Собранныйwebhook.ts ниже объединяет все три расширения с этой страницы: инструмент ответа, проверка отправителя и трансляция разрешений. Если вы начинаете отсюда, вам также потребуется настройка проекта и запись .mcp.json из начального пошагового руководства.
Чтобы сделать обе стороны тестируемыми из curl, слушатель HTTP обслуживает два пути:
GET /events: держит открытым поток SSE и отправляет каждое исходящее сообщение как строкуdata:, поэтомуcurl -Nможет смотреть ответы Claude и запросы разрешений в реальном времени.POST /: входящая сторона, тот же обработчик, что и раньше, теперь с проверкой формата вердикта, вставленной перед ветвью пересылки чата.
"Full
webhook.ts:
/events, включая пятибуквенный ID. Одобрите его с удалённой стороны:
reply и также попадает в поток.
Три специфичные для канала части в этом файле:
- Возможности в конструкторе
Server:claude/channelрегистрирует слушатель уведомлений,claude/channel/permissionсогласуется на трансляцию разрешений,toolsпозволяет Claude обнаружить инструмент ответа. - Исходящие пути: обработчик инструмента
reply— это то, что Claude вызывает для разговорных ответов; обработчик уведомленийPermissionRequestSchema— это то, что Claude Code вызывает при открытии диалога разрешения. Оба вызываютsend()для трансляции через/events, но они запускаются разными частями системы. - Обработчик HTTP:
GET /eventsдержит открытым поток SSE, чтобы curl мог смотреть исходящий в реальном времени;POSTвходящий, проверенный на заголовокX-Sender. Телоyes <id>илиno <id>переходит в Claude Code как уведомление вердикта и никогда не достигает Claude; всё остальное пересылается Claude как событие канала.
Упаковка как плагин
Чтобы сделать ваш канал устанавливаемым и общим, оберните его в плагин и опубликуйте на маркетплейс. Пользователи устанавливают его с/plugin install, затем включают его за сеанс с --channels plugin:<name>@<marketplace>.
Канал, опубликованный на вашем собственном маркетплейсе, по-прежнему требует --dangerously-load-development-channels для запуска, так как он не находится в одобренном списке разрешений. Чтобы его добавили, отправьте его на официальный маркетплейс. Плагины каналов проходят проверку безопасности перед одобрением. На планах Team и Enterprise администратор может вместо этого включить ваш плагин в список allowedChannelPlugins организации, который заменяет список разрешений Anthropic по умолчанию.
См. также
- Каналы для установки и использования Telegram, Discord, iMessage или демонстрации fakechat, а также для включения каналов для организации Team или Enterprise
- Рабочие реализации каналов для полного кода сервера с потоками спаривания, инструментами ответа и вложениями файлов
- MCP для базового протокола, который реализуют серверы каналов
- Плагины для упаковки вашего канала, чтобы пользователи могли установить его с
/plugin install