MCPサーバーのChannels連携を実装する

普段のMCPサーバーは、Claudeがツールを呼んだときだけ答えます。ここにclaude/channelというcapability(機能宣言)を1つ足すと、そのサーバーは外部で何かが起きた瞬間に、実行中のセッションへ自分から通知を送り込めるようになります。これがClaude Code Channelsで、既存のMCPサーバーを大きく作り直さずに対応させられる機能です。研究プレビュー段階のため、有効化にはセッション単位の明示的な有効化が要ります。

MCPサーバーがChannelsとして動く仕組みとは何か

Channelとは、claude/channel capabilityを宣言したMCPサーバーのことです。宣言があると、Claude Codeはそのサーバー用に通知リスナーを登録し、サーバー側がnotifications/claude/channelを送るたびにイベントを<channel>タグとしてClaudeの文脈に流し込みます。CIの失敗通知や監視アラートのような一方向のイベント転送も、Telegramのようなチャットの橋渡しも、同じ仕組みの上に成り立っています。

普通のMCPサーバーとの違いは「誰が会話を始めるか」です。通常のツール呼び出しはClaudeが必要になったときにサーバーへ問い合わせますが、Channelはサーバー側の都合でいつでもセッションに割り込めます。同じ「外から今動いているセッションに関わる」仕組みでも、Claude TagがSlackの@claudeメンションから新しいクラウドセッションを立ち上げるのに対し、Channelsはあなたがすでに開いているローカルセッションにイベントを送り込む点が異なります。

通常のMCPツール呼び出しとの違い

同じMCPサーバーでも、Channel対応の有無で挙動がまったく変わります。

ステップ1 — サーバーにclaude/channel capabilityを宣言する

自分のMCPサーバーをChannel化する最初の一歩は、Serverコンストラクタのcapabilitiesにclaude/channelを追加することです。

const mcp = new Server(
  { name: 'my-server', version: '0.0.1' },
  {
    capabilities: { experimental: { 'claude/channel': {} } },
    instructions: 'Events arrive as <channel source="my-server" ...>. One-way: read and act, no reply expected.',
  },
)

このキーが存在するだけで、Claude Codeはそのサーバーを通知の登録対象として認識します。instructionsは接続時にClaudeへ渡されるテキストで、どんなイベントが来るか・返信が必要かどうか・返信が必要ならどのツールでどの属性を渡すかをここに書いておきます。双方向のチャットブリッジにしたい場合は、標準のMCPツールとして返信用ツールを別途公開しますが、一方向のアラート転送だけならtoolsは省略して構いません。

ステップ2 — --channelsフラグでセッションを有効化する

capability(機能宣言)を宣言しただけでは、Channelとしては動きません。起動時に--channelsでそのサーバーを明示的に指定して初めて、セッションが通知を受け取るようになります。

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

自作サーバーの動作確認はclaude --dangerously-load-development-channels server:<name>で行います。--channelsはプレビュー中、承認済み一覧のプラグイン(plugin:<name>@<marketplace>)のみを受け付けます。この--channelsによるセッション単位の有効化は、.mcp.jsonのスコープ(local・project・user)とは別の軸です。.mcp.json側のスコープはサーバーをどこから読み込むかを決め、--channelsはそのセッションで通知を受け取るかどうかを決めます。両方が揃って初めてイベントが届きます。

Team・Enterpriseプランでは、管理者がchannelsEnabledをtrueにするまでどのユーザーも--channelsを使えません。有効化後はallowedChannelPluginsで、Anthropicの既定一覧を組織独自の一覧に置き換えることもできます。

MCPプロトコルネゴシエーションの落とし穴

v2のMCPクライアントランタイムを使っていて、環境変数MCP_PROTOCOL_NEGOTIATIONをautoに設定していると、サーバーがプロトコルリビジョン2026-07-28をネゴシエートした場合にChannelメッセージを配信できなくなり、Claude Codeはそのサーバーをそもそもチャンネルとして登録しません。エラーは表に出ず、単に通知が届かないだけなので原因に気づきにくいポイントです。この変数を未設定のままにするか、legacyに設定しておくと、stdioサーバーは従来のハンドシェイクを維持します。

通知は届いても確認応答が無い

mcp.notification()のawaitが解決するのは、メッセージがトランスポートに書き込まれた時点であって、Claudeがそれを処理した時点ではありません。セッションがそのサーバーをChannelとして読み込んでいない場合や、組織ポリシーがブロックしている場合、Claude Codeはイベントを黙って捨て、サーバー側にはエラーを返しません。確実に処理されたか知りたいなら、サーバー側でイベントの状態を追跡し、Claudeが状況を報告できる返信用ツールを別途公開する必要があります。

複数の通知が届いたタイミングでClaudeが作業中だった場合、それらはまとめて次のターンで配信され、Claudeはひとまとまりとして処理します。独立した2つのイベントストームを並行して扱いたいなら、セッション自体を分ける設計にします。もう1点、metaに付けられるキーは英数字とアンダースコアだけの識別子に限られ、ハイフンを含むキーは<channel>タグの属性として静かに落とされます。

認証とプラットフォームの制約

Channelsを使うにはclaude.aiアカウントかAnthropic ConsoleのAPIキーによる認証が必要で、Amazon Bedrock・Google Cloud's Agent Platform・Microsoft Foundryでは利用できません。組織に属さないPro・Maxユーザーはこうしたポリシーチェックの対象外で、--channelsをセッションごとに指定するだけで使えます。

管理者が使えるプラグインを絞りたい場合は、allowedChannelPluginsでAnthropicの既定一覧を組織独自の一覧に置き換えます。

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

空配列を設定すると一覧経由の起動はすべてブロックされますが、--dangerously-load-development-channelsはこの制限をバイパスできてしまいます。開発フラグも含めて完全に締め出したいなら、allowedChannelPluginsを空にするのではなくchannelsEnabled自体を未設定のままにします。

既存のMCP機能との重なりに注意する

Channel対応にしても、そのサーバーの通常のMCP挙動が消えるわけではありません。返信用ツールを呼び出した場合は、他のMCPツール呼び出しと同じくサーバーごとのtimeoutとアイドルタイムアウトの対象になり、メインの会話からの呼び出しが2分を超えて実行中だとバックグラウンドタスクに自動的に移されます(この自動バックグラウンド化はv2.1.212以降の挙動です)。Channelの通知そのものはこの仕組みの外にありますが、双方向チャンネルの返信ツールを設計するときは、この2つのタイムアウトが効くことを前提にしておく必要があります。

Claude Codeの他の連携方法との違い

外部からClaude Codeのセッションに関わる方法は、Channelsだけではありません。何を任せたいかによって向き不向きが分かれます。

この機能はどこまで安定しているか

Channelsは研究プレビュー段階の機能で、--channelsのフラグ仕様やプロトコルの契約はフィードバックをもとに変わる可能性があります。--channelsも--dangerously-load-development-channelsもclaude --helpには表示されませんが、フラグ自体は動作します。自作のサーバーを試す間は開発フラグで承認済み一覧をバイパスし、配布する段階になったらClaude Codeプラグイン完全ガイドの手順でプラグイン化し、マーケットプレイスに公開したうえで正式な一覧入りを別途調整します。プラグインを更新した後にサーバーを新しいバージョンへ切り替えるには/reload-pluginsを実行します。

よくあるつまずき

• --channelsを付け忘れて通知が届かない: サーバー自体は普通に接続されツールも動きますが、Channelとしての通知だけは配信されません
• MCP_PROTOCOL_NEGOTIATION=autoで登録されない: v2ランタイムでプロトコルリビジョン2026-07-28をネゴシエートするサーバーはChannelとして登録されず、エラーも出ません
• metaのキーにハイフンを使って値が消える: metaのキーは英数字とアンダースコアの識別子のみです
• 組織のchannelsEnabledが未設定でブロックされる: claude.ai Team/Enterpriseでは既定でブロックされており、Owner権限での有効化が必要です

よくある質問

既存のMCPサーバーをそのままChannelsに対応させられますか

capabilities.experimentalにclaude/channelを追加し、notifications/claude/channelを送るコードを足すだけで対応できます。既存のツール呼び出し用のハンドラを書き直す必要はありません。

通知が届いたことをサーバー側で確認する方法はありますか

標準の仕組みではありません。mcp.notification()のawaitはトランスポートへの書き込み完了で解決し、Claudeの処理完了を意味しません。確認が必要なら、返信用のMCPツールを別途公開し、Claudeにステータスを報告させる設計にします。

Channelsは本番運用に使える段階ですか

研究プレビュー段階です。フラグの構文やプロトコルの契約が今後変わる可能性がある前提で使う機能です。

まとめ

MCPサーバーをChannelとして動かすには、claude/channel capability(機能宣言)の宣言、起動時の--channelsによるセッション単位の有効化、そして組織のchannelsEnabledポリシーという3つの条件がすべて揃う必要があります。MCP_PROTOCOL_NEGOTIATION=autoとの相性や、通知に確認応答が無い点は見落としやすい落とし穴です。まず--dangerously-load-development-channelsで手元のサーバーを試し、要件が固まってから配布に進むと手戻りが少なくて済みます。サーバーの基本的な追加方法自体はClaude Code MCP設定ガイドで扱っています。