Channels — Push Events Into a Running Session

Channels are MCP servers that push events into your running Claude Code session so Claude can react to external events without polling. Requires Claude Code v2.1.80+, claude.ai login (no Console/API key auth).

What Channels Are

An MCP server that delivers messages to your session rather than waiting to be queried
Two-way: Claude reads the event and replies back through the same channel
Events only arrive while the session is open — for always-on use, run Claude in a background/persistent terminal
Installed as a plugin, configured with your own credentials

Supported Channels

All require Bun to run:

Channel	Notes
Telegram	Official plugin, pairing-code auth
Discord	Official plugin, pairing-code auth
iMessage	Auth via texting yourself; add contacts with `/imessage:access allow`
fakechat	Demo only — localhost UI, no credentials needed

You can also build a custom channel.

How to Enable

Install the channel as a plugin
Pass --channels <plugin-name> when starting Claude Code
Being in .mcp.json alone is not enough — the server must also be named in --channels

Security Model

Each channel maintains a sender allowlist — only approved IDs deliver messages
Telegram/Discord: bootstrap via pairing code exchange; Claude prompts you to approve
iMessage: texts from yourself auto-approved; others added with /imessage:access allow
Allowlist also gates permission relay — anyone on the list can approve/deny tool use remotely
Only allowlist senders you trust with that authority

Permission Handling While Away

If Claude hits a permission prompt while you're away:

Session pauses until you respond
Channels that declare the permission relay capability can forward prompts to you for remote approval/denial
--dangerously-skip-permissions bypasses all prompts — use only in trusted environments

Enterprise Controls

Channels are off by default on Team and Enterprise plans.

Setting	Effect	Default
`channelsEnabled`	Master switch — must be `true` for any channel to work	Channels blocked
`allowedChannelPlugins`	Override Anthropic's default plugin allowlist with your own	Anthropic default list

Pro/Max individual users skip these checks entirely
Admins configure via claude.ai Admin settings → Claude Code → Channels
allowedChannelPlugins replaces (not extends) the Anthropic list when set

{
  "channelsEnabled": true,
  "allowedChannelPlugins": [
    { "marketplace": "claude-plugins-official", "plugin": "telegram" },
    { "marketplace": "acme-corp-plugins", "plugin": "internal-alerts" }
  ]
}

Primary Use Cases

Chat bridge: ask Claude from your phone via Telegram/Discord/iMessage; answer appears in same chat while work runs locally against your real files
Webhook receiver: CI results, error tracker alerts, deploy pipeline events arrive where Claude already has your files open and remembers what you were debugging

How Channels Compare to Other Features

Feature	Push vs Pull	Use when
Channels	Push into running local session	React to external events in real time
Standard MCP server	Pull (Claude queries it)	Give Claude on-demand read/query access
wiki/claude-code/overview	Async cloud sandbox	Delegate self-contained async work
Remote Control	You drive your local session	Steer in-progress session from phone/web
Scheduled tasks	Timer-based poll	Regular checks, not event-driven

Research Preview Caveats

--channels only accepts plugins from the Anthropic allowlist (or org allowlist)
Syntax and protocol contract may change
Use --dangerously-load-development-channels to test custom channels you're building

Key Takeaways

Channels solve the push problem: standard MCP is pull-only, channels deliver events to your session
Requires explicit opt-in per session via --channels flag
Security is enforced by a sender allowlist — not just by being in .mcp.json
Enterprise orgs must enable channelsEnabled before any channel delivers messages
The allowlist double-gates permission relay — anyone on it can approve tool use remotely, so vet carefully
For always-on reactivity, run Claude in a persistent/background terminal session

wiki/claude-code/mcp-integration — standard (pull) MCP setup
wiki/claude-code/overview — surfaces, capabilities, CLI flags
wiki/claude-code/create-plugins — how to build your own channel plugin
wiki/claude-code/agent-teams — multi-session orchestration

Source: raw/Push events into a running session with channels.md

5.4 KiB Raw Permalink Blame History