Skip to main content
AI/MLagentfront

frontmcp-channels

Use when you want to push real-time notifications into Claude Code sessions. Build webhook channels, chat bridges (WhatsApp, Telegram, Slack), agent completion alerts, job status notifications, or error forwarding. The skill for CHANNELS and NOTIFICATIONS.

Stars
144
Source
agentfront/frontmcp
Updated
2026-05-30
Slug
agentfront--frontmcp--frontmcp-channels
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/agentfront/frontmcp/HEAD/libs/skills/catalog/frontmcp-channels/SKILL.md -o .claude/skills/frontmcp-channels.md

Drops the SKILL.md into .claude/skills/frontmcp-channels.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

FrontMCP Channels

Build push-based notification channels that stream real-time events into Claude Code. Channels let your MCP server forward webhooks, application errors, agent completions, job results, and chat messages directly into Claude's context, with optional two-way reply support.

When to Use This Skill

Must Use

  • You need Claude Code to react to external events (CI failures, monitoring alerts, deploy status)
  • You are building a chat bridge (WhatsApp, Telegram, Slack, Discord) for Claude Code
  • You want agents or background jobs to notify Claude Code upon completion

Recommended

  • You want to forward application errors to Claude for debugging assistance
  • You need a messaging interface where remote users can interact with Claude via chat platforms

Skip When

  • You only need standard MCP resource subscriptions (use @Resource with resources/subscribe)
  • Your client is not Claude Code and does not support experimental['claude/channel']
  • You need request-response patterns (use @Tool instead)

Decision: Use channels when you need server-initiated push notifications into Claude Code. Use resources when the client pulls data on demand.

Prerequisites

  • @frontmcp/sdk >= 1.0.0
  • Basic understanding of @FrontMcp, @App, and @Tool decorators
  • For webhook sources: HTTP transport (not stdio-only)
  • For chat bridges: external API credentials (WhatsApp Business API, Telegram Bot Token, etc.)

Steps

  1. Choose your channel source type from the Scenario Routing Table
  2. Create a channel class or function
  3. Register it in your app
  4. Enable channels in @FrontMcp config
  5. Test with Claude Code using --dangerously-load-development-channels

Scenario Routing Table

Scenario Reference Description
Webhook alerts (CI, monitoring) references/channel-sources.md Forward HTTP webhooks into Claude
Application error forwarding references/channel-sources.md Push app errors via event bus
Agent completion notifications references/channel-sources.md Notify when agents finish
Job/workflow completion references/channel-sources.md Notify when jobs complete
Service connector (WhatsApp, etc.) references/channel-sources.md Persistent connection with bidirectional tools
File/log watcher references/channel-sources.md File system change monitoring
Event replay for offline sessions references/channel-sources.md Buffer events for later delivery
WhatsApp/Telegram chat bridge references/channel-two-way.md Two-way messaging with Claude
Slack/Discord integration references/channel-two-way.md Chat platform bridges
Permission relay references/channel-two-way.md Remote tool approval via chat

Common Patterns

Pattern Correct Incorrect Why
Meta keys meta: { env: 'prod' } meta: { 'my-env': 'prod' } Meta keys must be valid identifiers (letters, digits, underscores)
Source naming name: 'deploy-alerts' name: 'Deploy Alerts!' Channel names should be kebab-case identifiers
Two-way gating Check sender identity before emitting Trust room/group membership Prevent prompt injection from untrusted group members
Error channels Use app-event source with event bus Poll for errors in a loop Event bus is push-based and efficient
Manual push Use scope.channelNotifications.send() Call pushNotification on instance directly Service handles capability filtering

Verification Checklist

Server Setup

  • @FrontMcp({ channels: { enabled: true } }) is set
  • Channel classes extend ChannelContext with @Channel() decorator
  • Channels are listed in @App({ channels: [...] })
  • onEvent() returns { content: string, meta?: Record<string, string> }

Capability

  • Server advertises experimental: { 'claude/channel': {} } in capabilities
  • Only sessions with matching capability receive notifications
  • instructions field mentions <channel> tags when channels are active

Two-Way

  • twoWay: true is set on channels that need replies
  • channel-reply tool appears in tool list
  • onReply() is implemented and forwards to external system
  • Sender authentication is enforced before emitting events

Sources

  • Webhook endpoints return 200 on success
  • Event bus subscriptions are cleaned up on scope teardown
  • Agent/job completion filters match expected IDs

Troubleshooting

Problem Cause Solution
No notifications arrive Client doesn't support channels Check client capabilities include experimental['claude/channel']
channel-reply tool missing No two-way channels registered Set twoWay: true on at least one channel
Webhook returns 500 onEvent() throws Check channel handler error logs
Duplicate notifications Multiple sessions subscribed This is correct behavior -- each session gets its own copy
Events lost on reconnect Channels are in-memory Channel state resets on server restart; use persistent sources

Examples

Each reference has matching examples under examples/<reference>/:

channel-sources

Example Level Description
webhook-github Basic Forward GitHub webhook events (PRs, pushes, CI) into Claude Code
app-errors Basic Forward application errors to Claude Code via the in-process event bus
agent-notify Intermediate Notify Claude Code when AI agents complete their tasks
job-completion Intermediate Notify Claude Code when background jobs and workflows complete
service-connector Advanced Build a persistent service connector that lets Claude send and receive messages through WhatsApp, Telegram, or any messaging API
file-watcher Intermediate Watch files for changes and notify Claude Code in real-time
replay-buffer Advanced Buffer channel events so Claude Code receives them when it connects, even if events occurred while offline

channel-two-way

Example Level Description
whatsapp-bridge Advanced Full WhatsApp Business API bridge allowing users to chat with Claude Code via WhatsApp

Accessing This Skill

Skills are distributed as plain SKILL.md files plus a sibling references/ and examples/ tree, so consumers can pick whichever access mode fits:

Mode How it works
Filesystem Read libs/skills/catalog/frontmcp-channels/ directly from a clone of the catalog repo, or from a published @frontmcp/skills install. SKILL.md is the entry point.
frontmcp CLI frontmcp skills list, frontmcp skills read frontmcp-channels, frontmcp skills read frontmcp-channels:references/<file>.md, frontmcp skills install frontmcp-channels — no server required.
MCP skill:// When a developer mounts this skill into their own FrontMCP server (@FrontMcp({ skills: [...] })), the SDK exposes it via SEP-2640 resources: skill://frontmcp-channels/SKILL.md, skill://frontmcp-channels/references/{file}.md, etc. The server’s skill://index.json returns the SEP-2640 discovery document for everything mounted on it.

The catalog itself is not an MCP server. The skill:// URIs only resolve when a server has been configured to host this skill.

Reference