Channels: Push Events into Sessions

The gap that channels fill

Standard MCP is pull-based: Claude calls a tool, the server responds, and the session moves forward. But some workflows need the opposite — external events arriving in the session unprompted, while you are doing something else. A CI pipeline finishes. Sentry fires an alert. Someone sends you a message on Telegram asking Claude to check something.

Channels fill this gap. A channel is a special type of MCP server that pushes events directly into your running Claude Code session. When an event arrives, Claude reads it and responds — calling tools, checking files, or sending a reply back through the same channel. You get a bidirectional bridge between Claude and any external system that can reach the channel server.

How channels compare to other remote features

Enabling a channel: the --channels flag

Being in .mcp.json or configured via claude mcp add is not enough to activate a channel. A server must also be named in the --channels flag when you launch Claude Code:

claude --channels plugin:telegram@claude-plugins-official

This design is intentional: channels have significant permissions — they push messages into your session and can trigger tool use on your machine. Opting in explicitly each session ensures you are always aware of which channels are active. You can pass multiple plugins space-separated to enable several channels at once.

Channels do not persist across session restarts. Every time you close and reopen Claude Code, you must pass --channels again. For always-on use — receiving CI alerts, running a persistent chat bridge — run Claude in a persistent terminal or a background process that stays alive between your work sessions.

Supported channels: Telegram, Discord, iMessage

The research preview includes three officially supported channels, each installed as a plugin requiring Bun. The setup pattern is the same for all three:

1. Create a bot on the platform (BotFather for Telegram, Discord Developer Portal for Discord; iMessage needs no bot).
2. Install the plugin in Claude Code: /plugin install telegram@claude-plugins-official
3. Run the configure command with your bot token: /telegram:configure <token>
4. Restart with --channels to activate the server.
5. Send your bot a message to trigger the pairing flow.

iMessage is the simplest: no bot token is required. The plugin reads your Messages database directly and sends replies via AppleScript. It requires Full Disk Access permission in System Settings for the terminal app that launches Bun. Texting yourself bypasses the access gate automatically. Add other contacts with /imessage:access allow +15551234567.

The fakechat quickstart for testing

Before connecting a real platform, test the channel setup with the fakechat demo plugin. It runs a chat UI on localhost:8787 — no authentication, no external service required:

/plugin install fakechat@claude-plugins-official claude --channels plugin:fakechat@claude-plugins-official

Open localhost:8787 in your browser, type a message, and watch it arrive in your Claude Code session. Claude reads the event, does the work, and sends the reply back to the browser UI. Use fakechat to verify your channel setup before configuring Telegram credentials.

Securing your channel: sender allowlist and pairing

Every channel plugin maintains a sender allowlist. Only sender IDs on the list can push messages into Claude Code; everyone else is silently dropped. Telegram and Discord bootstrap the list through a pairing flow: send any message to your bot, receive a pairing code, approve it in Claude Code with /telegram:access pair <code>, then lock down access with /telegram:access policy allowlist. Without the policy step, anyone who knows your bot can reach Claude.

Some channels support permission relay: if a tool call requires approval while you are away from the terminal, the channel can forward the permission prompt to you through the chat interface. Anyone on the sender allowlist can respond to these prompts, so allowlist only senders you trust with that authority.

Enterprise controls: channelsEnabled and allowedChannelPlugins

On Claude.ai Team and Enterprise plans, channels are blocked by default until an Owner enables them. The channelsEnabled managed setting controls availability — true enables channels for the organization, false (or unset on Team/Enterprise) blocks them. On Console plans using API key authentication, channels are permitted by default.

Organizations can also restrict which channel plugins can register using allowedChannelPlugins in managed settings. Setting this replaces the Anthropic-maintained default allowlist entirely — only listed plugins can register as channels. An empty array blocks all plugins from the allowlist while still allowing development channels via --dangerously-load-development-channels.