sample-mcp-apps-in-claudeai

MCP Apps の機能を、claude.ai をホストにして実際に動かして確かめるためのサンプルです。題材は付箋ボードで、 Claude が書いた付箋を View（claude.ai の会話の中に表示される iframe）に貼り、ユーザーと Claude の両方が付箋を動かせます。

View と Host（claude.ai）の間でやりとりしたものは、すべて View の下のログに出ます。同じ内容は MCP サーバーのターミナルにも JSON で 1 行ずつ出るので、View が消えたあとに届くもの（ui/resource-teardown）も確かめられます。

確かめられること

View→Host

• ui/open-link: 付箋の「検索」ボタン。付箋の本文で Web 検索のページを開く

• ui/message: 付箋の「掘り下げて」ボタン。「付箋『…』を掘り下げて」を会話に送る

• ui/request-display-mode: 「全画面」「戻す」ボタン。inline と fullscreen を切り替える

• ui/update-model-context: 付箋を足す・消す・書き換える・並べ替えると、1 秒おいてボード全体を Claude の文脈に送る

• ui/download-file: 「.md で書き出す」ボタン。付箋を Markdown の箇条書きにして書き出す

• ui/notifications/request-teardown: 「ボードを閉じる」ボタン。View を閉じるようホストに頼む。 応じるかどうかはホストが決めるので、3 秒待っても ui/resource-teardown が来なければ、そう画面とログに出す

• ui/notifications/size-changed: 付箋が増えて View が高くなると、SDK が自動で送る。送った幅と高さをログに出す

Host→View

• ui/notifications/tool-input-partial: Claude が show_board の引数を書いている途中で、そこまでの引数が届く。 届いた回数と、最後の partial の時点で引数がそろっていたかを「tool-input-partial のまとめ」としてログに出す

• ui/notifications/tool-input: 引数がそろうと届く

• ui/notifications/tool-result: show_board の結果が返ると届く

• ui/notifications/tool-cancelled: show_board の実行中に会話を止めると届く。理由（reason）を画面に出す

• ui/notifications/host-context-changed: テーマや表示モード、枠の大きさが変わると届く。View のテーマに反映する

• ui/resource-teardown: View が破棄される前に届く。サーバーにログを送り終えてから応答する

• あわせて、View が消える瞬間（pagehide）もログに残す。iframe が消えるときは通信も止まるので、届かないこともある

App 提供ツール

View が app.registerTool で、次の 2 つのツールを Claude に出します。Claude はユーザーが開いている View を直接操作できます。

• edit_board: 付箋を追加・書き換え・削除する

• read_board: 今の付箋（id・本文・色・並び順）を読む

claude.ai の App 提供ツールは、2026 年 11 月の時点では public preview で、一部の組織でしか使えません （公式ドキュメント）。使えるかどうかは試して確かめるしかありません。 次の条件もあります。

• MCP サーバーがリモート（URL で登録するカスタムコネクタ）であること。このサンプルはトンネルで公開するので満たします

• unified experience（Chat と Cowork の統合）が有効であること。入力欄で Chat と Cowork を選べる状態なら無効です。 Team と Enterprise では、組織の Owner が設定の Capabilities で有効にします

• Claude にツールが渡るのは、View が開いている間だけです。会話で最初に View を開いたメッセージでは渡らず、次のメッセージから渡ります

View が開くと、ログの最初の行（「接続した」）にホストの capabilities が出ます。

Related MCP server: Shared Whiteboard

必要なもの

• Node.js 24 と pnpm

• cloudflared（brew install cloudflared）。外から届く URL を作れれば、ほかのトンネルでもかまいません

• カスタムコネクタを追加できる claude.ai のアカウント

動かし方

1. 依存を入れる

   pnpm install

2. サーバーを起動する。PATH_TOKEN は URL に入れる推測しにくい文字列です。固定しておくと、起動し直してもコネクタを登録し直さずに済みます

   PATH_TOKEN=$(openssl rand -hex 16) pnpm start

   PATH_TOKEN を省くと起動のたびに作り、ターミナルに表示します。ポートは既定で 3000 で、PORT で変えられます。 サーバーは 127.0.0.1 だけで待ち受けます。

3. 別のターミナルでトンネルを開く

   cloudflared tunnel --url http://127.0.0.1:3000

   数秒すると、ターミナルに https://xxxx-xxxx-xxxx.trycloudflare.com のような URL が出ます。これがトンネルのホストです。 ログが流れて見失ったら、trycloudflare.com で探してください。ホスト名は cloudflared を起動するたびに変わるので、 開き直したらコネクタの URL も登録し直します

4. claude.ai の「設定 > コネクタ」で、カスタムコネクタに https://<トンネルのホスト>/mcp/<PATH_TOKEN> を追加する

5. 終わったら、トンネルとサーバーを止めて、コネクタを外す

ログの読み方

• サーバーのターミナルの 1 行が、View で起きた 1 つの出来事です。view はどの View（ボード）か、seq はその View の中で起きた順の番号です。 View からの送信は待たずに投げるので、ターミナルでは時刻の順に並ばないことがあります。順番は seq で追ってください

• server で始まる行は、サーバー自身のログです。show_board が呼ばれた・結果を返した・中断された（リクエストが取り消された）ときに出ます

試し方

新しいチャットで、上から順に送ると、このアプリの機能を一通り使えます。やりとりは View の下のログと、サーバーのターミナルで確かめます。

1. 「sticky-board で、休日の過ごし方の付箋ボードを作って。付箋は 8 枚」と頼む

2. 付箋を書き換えたり、「←」「→」で並べ替えたり、「付箋を追加」から足したりしてから、「今のボードで一番手軽なのはどれ？」と聞く

3. 付箋の「掘り下げて」「検索」、上の「全画面」「.md で書き出す」を押す

4. 「ボードに『昼寝をする』を足して、一番上の付箋を消して」と頼む（App 提供ツール）

5. 「sticky-board で、新しい趣味の付箋ボードを作って。付箋は 5 枚、delay_seconds は 30」と頼み、ボードが開いたら会話を止める。 delay_seconds は、サーバーが結果を返すまで待つ秒数で、実行中に止めるための検証用の引数です

6. claude.ai のテーマ（ライト / ダーク）を切り替える、ウィンドウの幅を変える

7. 「ボードを閉じる」を押す、または会話を離れる

作りについて

• src/server.ts: MCP サーバー。View を開く show_board と、View だけが呼べる log_event（ログをターミナルに出す）を持つ

• src/ui/main.ts: View。@modelcontextprotocol/ext-apps の App で Host とやりとりする

• scripts/build-ui.mjs: View のスクリプトを esbuild でまとめ、1 つの HTML（dist/ui.html）にする

View で加えた変更は保存しません。会話を開き直すなどして View が作り直されると、show_board を呼んだときの付箋に戻ります。

ライセンス

MIT