MCP AppsとVonageでClaude Desktopにレポートダッシュボードを構築する

このチュートリアルでは、Claude Desktop内にリアルタイムレポートダッシュボードを作成します。

はじめに

「SMSがダウンしている。

チームから得られる情報はそれだけだ。詳細なし。ログもない。

地域の問題か？キャリアの問題？アプリのバグ？これらの質問に答えるには、通常、ダッシュボードを飛び回り、レポートをエクスポートし、データを手動で評価する必要がある。あるいは、APIと照合するスクリプトを素早く書くこともできるだろう。いずれにせよ、それは高速ではない。また、プレッシャーの中でやりたいことでもない。

もし、あなたが毎日使っているチャットの中で、そのすべてを直接調査できるとしたら？

モデル・コンテキスト・プロトコル（MCP）アプリがそれを可能にする。MCPアプリは、AIツールのGUIモーメントだと考えてください。グラフィカル・インターフェイスが専門家を超えてコンピューティングにアクセスできるようにしたのと同じように、MCPアプリはAIエージェントに接続するMCPツールに真のインタラクティブ性をもたらします。

この投稿では、MCP Apps フレームワークを使用して Claude Desktop 内で実行されるレポート・ダッシュボードを構築する方法を学びます。これはVonageのReporting APIに接続し、生のレコードをリアルタイムで何が起こっているかを理解できるインタラクティブなUIに変えます。

>> TL;DR：先にスキップして クイックスタートとアプリのコードはGitHub.

Claude Desktop showing the MCP App SMS report dashboard with filters for date range, status, and phone numbers.

前提条件

始める前に、あなたが持っていることを確認してください：

• クロード・デスクトップ

• Vonage APIアカウント

• Node.js 18歳以上

  • ソースからビルドする場合のみ必要で、ビルド済みリリースでは必要ない。

MCPアプリの仕組み

MCPアプリとMCPサーバーの比較

もしあなたが モデル・コンテキスト・プロトコルをご存知なら、MCPサーバーについてご存知でしょう。ツールやリソースを提供することで、AIエージェントの能力を拡張します。MCPサーバーは MCPツーリングサーバーのようなエンドポイントを公開します。 send_smsまたは get_records_reportのようなエンドポイントを公開します。

MCPアプリは違います。AIエージェント内に直接インタラクティブUIをバンドルしたMCPサーバーです。つまり、ボタン、フィルター、フォーム、複雑なUI要素にアクセスできます。

MCPアプリは、プレーンテキストの応答だけでは十分でない場合に本当に便利です。大規模なデータセットの調査、複数の入力があるシステムの設定、ライブアクティビティの監視、複数段階のワークフローのステップなど、インタラクティブなUIはこれらのタスクをより速く、より簡単に推論することができます。前後の会話の代わりに、ユーザーは一度にすべてを見ることができ、直接対話することができます。

Example of an MCP App rendering an interactive dashboard UI directly inside a chat interface.

システムの流れ

レポートを実行するとこうなる：

1. クロードのダッシュボードを操作する

2. ダッシュボードはMCP Appサーバー上のツールを呼び出します。

3. サーバーは上流のVonage MCPサーバーを呼び出します。

4. Vonage MCP サーバは Vonage Reports API をヒットします。

5. データはチェーンを通して逆流する

6. サーバーはそれを正規化してマスクし、UIに返す。

7. ダッシュボードは結果をインラインでレンダリングする

System flow diagram showing how an MCP App in Claude Desktop connects to the Vonage Reports API and returns data to an embedded UI.

サーバーは生のAPIデータとインタラクティブなインターフェースの橋渡しをします。Vonage API レスポンスを正規化し、機密性の高い電話番号を表示する前にマスクし、UI が消費するデータを構造化します。

どのように組み立てられているか

1. サーバー (src/server.ts)

   サーバは2つのツール(sms_reportと voice_report)を登録し、UIとVonageの間のプロキシとして動作する。を呼び出すのではなく Vonage Reports APIを直接呼び出すのではなく、既存のTooling MCPサーバをサブプロセスとしてラップし、あなたの代わりに呼び出します。 get-records-reportを呼び出し、表示のために応答を正規化します。認証、リクエスト署名、エラー処理はすべてVonage MCPサーバーに残ります。認証、リクエスト署名、エラー処理はすべてVonage MCPサーバーに残ります。私たちのサーバーはデータを整形し、UIに渡すだけです。

2. UI (src/ui/mcp-app.ts)

   これはインタラクティブなHTMLダッシュボードを生成します。これは、日付ピッカー、ステータスフィルター、ページ分割されたテーブル、拡張可能な行の詳細を、Viteの vite-plugin-singlefile.各ツールの登録にそのポインタが含まれているため、Claude内部でレンダリングされます：

   "_meta": 
     { "ui":
       { "resourceUri": "ui://vonage-reports/mcp-app.html" 
       }
     }

   コピー

   Claude Desktopはそのメタデータを見ると、プレーンテキストを返す代わりにインターフェイスをインラインでレンダリングする。そこから、UIはクライアント側ですべてを管理する。 app.callServerTool()を呼び出してデータをフェッチし、ページネーションとアクティブなフィルタを追跡し、KPI カードのクリックトゥフィルタと、メッセージと通話の詳細のための行展開を処理します。

3. データ安全性

   電話番号は、データがUIに届く前にサーバー側でマスクされる。下4桁は保存され、それ以外はすべて置き換えられます。つまり、エクスポート、スクリーンショット、クリップボードコピーによって、たとえ偶発的であっても完全な番号が漏れることはありません。

5分でインストール

ステップ1：リリースをダウンロードする

GitHubの GitHubリリースページにアクセスして vonage-reports-mcp-app-v0.1.0.tar.gz.それをあなたのマシンのフォルダ（例：~/vonage-reports-app/）に解凍する。

tar -xzf vonage-reports-mcp-app-v0.1.0.tar.gz -C ~/vonage-reports-app/

ステップ 2: クロードデスクトップ設定に追加する

あなたの店を開く claude_desktop_config.json

• にあります。 ~/Library/Application Support/Claude/にあります。 %APPDATA%\Claude\Windowsでは

• このエントリーを mcpServersオブジェクトに追加します：

{
  "vonage-reports": {
    "command": "node",
    "args": ["/path/to/vonage-reports-app/dist/server.js"],
    "env": {
      "VONAGE_API_KEY": "your_api_key",
"VONAGE_API_SECRET": "your_api_secret",
       "VONAGE_APPLICATION_ID": "your_app_id",
       "VONAGE_PRIVATE_KEY64": "your_private_key_base64",
       "VONAGE_VIRTUAL_NUMBER": "your_virtual_number"
    }
  }
}

• パスと認証情報を実際の値に置き換えてください。

  • API クレデンシャルは Vonage API 設定.

ステップ 3: クロードデスクトップを再起動する

クロードを完全に終了し、再度開きます。起動時にMCPアプリが初期化されます。

ステップ4：ダッシュボードを開く

Claude では、MCP Apps セクションで Vonage Reports Dashboard を探してください。2つのタブがあります：SMSレポートとVoiceレポートです。これで準備完了です！

最初のレポートを実行する

UIを起動するには、次のようなプロンプトでツールを呼び出す必要がある、 "SMSレポートを実行する".そうすれば、フォームとダッシュボードにアクセスできる。

Claude Desktop displaying the MCP App SMS report dashboard with filters applied and results summarized in KPI cards.

SMSレポート

1. 日付範囲の設定

   • 日付/時間ピッカーを使って範囲を選択する（過去7日間など）。

2. ステータスによるフィルタリング（オプション）

   • ステータス」ドロップダウンをクリックし、配信済み、失敗、拒否などの値を選択します。

3. 送信者または受信者によるフィルタリング（オプション）

   • E.164形式の電話番号を入力します（例：+12025550123）。

4. メッセージの内容を含める（オプション）

   • 結果に実際のSMS本文を表示したい場合は、このボックスをチェックしてください。(⚠警告: メッセージ本文には個人情報が含まれている可能性があります)

5. レポートの実行」をクリックする

   • ダッシュボードはあなたの記録を取得し、表示します。

見どころ

• KPIカード

  • 上部には、メッセージの内訳を示す色付きのステータスカードが表示されます：

    • 緑＝配達済み

    • 赤＝不合格または却下

    • 黄色＝提出済み、受理済み、またはバッファ済み

    • グレー = 期限切れ、削除済み、または不明

  • いずれかのカードをクリックすると、その行だけにフィルタリングされます。フィルタを解除するには、もう一度クリックしてください。

• ページ分割テーブル

  • 結果テーブルには、日付、送信元、送信先、ステータス、ネットワーク、国、価格などのカラムを持つ1ページあたり10レコードが表示されます。長い値（内部参照IDなど）は、ホバー時にツールチップで切り捨てられます。

• 拡張可能なメッセージ

  • メッセージの内容を含める」を有効にすると、実際のメッセージ本文を含む行に ▶ msg ボタンが表示されます。クリックすると拡大され、メッセージの全文が表示されます。

• CSVコピー

  • CSVコピー」ボタンをクリックすると、現在の結果がクリップボードにエクスポートされます。スプレッドシートやテキストエディタに貼り付けます。

Detailed SMS report results displayed in the MCP App dashboard with KPI summaries and a paginated data table.

Voiceレポート

Voice Reportタブも同様に機能します。日付範囲を選択し、オプションでステータスまたは通話方向（インバウンド/アウトバウンド）でフィルタリングし、レポートを実行します。結果には、通話開始日、通話時間、発信/着信番号、ステータスなどが表示されます。行の▶ボタンをクリックすると、そのコールで使用可能なすべてのフィールドが表示されます。

Claude Desktop displaying the MCP App Voice report dashboard with call filters and detailed results.

どのように建設されたか

このMCPアプリはAIエージェントを使用して構築されました（WindsurfのGPT 5.2から始まり、Claude DesktopのClaude Codeに移行しました）ので、ステップバイステップのチュートリアルは確率的コーディングでは少し難しいです。どんなアプリでもそうですが、これはクリーンで直線的なビルドではありませんでした。以下に概要を示す4つの主な段階を経た。

プロジェクト設定

クロード・コードに加えて、私はエージェントにいくつかのリソースを与える必要があった：

• インストールする MCPアプリのスキル

• Vonage MCPツーリングサーバーおよび ドキュメントサーバー

MCP Apps スキルにより、エージェントは MCP App の構築方法を理解できます。ツール・サーバは、エージェントにReports APIを呼び出すツールへのアクセスを提供します。 get-records-reportツールへのアクセスを提供します。そして最後に、Documentation Serverは、エージェントがVonage APIがどのように動作するかを正確に理解し、潜在的に答えを幻覚したり、インターネットリソースから古いドキュメントを使用する代わりに、最新のドキュメントを使用するのに役立ちます。

1.AIによるプランニング

プロジェクトはひとつのプロンプトから始まった：

"私は、Vonage Developer Blogのために、クールで有意義なMCPアプリを作りたいのです。 Get-records-reportツールを使って。先週送信されたすべてのアウトバウンドSMSのレポートを取得できますか?''Voice Call ID 1234-abcd-5678-efghのレポートを取得できますか?

そのようなアプリケーションの作り方の概要を教えてください。

そこから、GPT5.2は一連のスコーピング・クエスチョンを行った：

• 機能はどの程度洗練されている必要がありますか？単なるデモなのか、それともほとんど製品化できるようなものなのか？

• UIをデータレイヤーに配線するには？

• メッセージ内容に含まれる個人を特定できる情報（PII）をどのように扱うか？例：電話番号とメッセージ内容

これらの質問にすべて答えた後、エージェントは、アーキテクチャ、2タブのUI構造、プロキシパターン、およびデータ安全性のデフォルトを前もって定義した完全な実装計画を準備しました。完全な 初期計画.

2.実行させる

最初のバージョンは ウィンドサーフ.しかし、実際にチャット内でアプリを動作させることができませんでした。CursorとVS Codeに移行しようとしました。理論的には、MCPアプリはこれらすべての環境で動作します。しかし、このことを理解するのにかかった時間は、実際にアプリを作るのにかかった時間よりもずっと長かった。

MCPアプリがUIをレンダリングするデフォルト環境はクロード・デスクトップだ。だから私はそれをダウンロードした。Vonageの認証情報を適切に設定すると、すぐに機能した！ダッシュボードは最初のトライで表示された。

MCPアプリを作るなら、初日からクロードデスクトップでテストしよう。環境と戦わないでください。

3.デバッグ

アプリが Claude Desktop で実行されると、4 つのコードレベルの問題を解決する必要がありました。Vonage Docs MCPサーバーがあることで、エージェントがVonageやMCP Appsの動作について間違った仮定をしている箇所をすぐに見つけることができたからです。

1. 最初の問題は、構造化されたコンテンツが入力されないことだった。ext-appsフレームワーク(MCP Apps)は、ツールがテキスト・レスポンスと一緒にフィールドを返すことを要求している。 structuredContentフィールドを返す必要があります。しかし、Vonage MCPサーバーはフィールドとして返さない。 structuredContentをフィールドとして返しません。それは、すべてを content[0].text.サーバは res.structuredContentフレームワークの検証は失敗しました。修正は extractStructured()ヘルパーです。

2. Vonageのレスポンスには人間が読める接頭辞がついている。この問題を修正しても structuredContent問題を修正しても JSON.parse()はまだ失敗していた。Vonageサーバーからの生テキストは以下のようになる：
   
   

   Records report for SMS:
   Total records: 47
   {"records": [...]}

   コピー

   プレーン JSON.parse()を実行すると、プレフィックスが原因で失敗する。修正方法は、解析前にJSONブロックだけを抽出する正規表現でした。

3. 音声レポートツールとMCP Apps間のスキーマタイプの不一致

   
   Voiceツールの outputSchema使用される z.record()をルートレベルで使います。ext-appsフレームワークには z.object() — z.record(),を必要とするため、ランタイムクラッシュ（Cannot read properties of undefined (reading '_zod'））が発生した。ちょっとした変更ですが、エラーメッセージで明らかになったわけではありません。

4. Voiceコールで必須パラメータが見つからないオリジナルのVoiceツールは、Vonage APIへの送信のみ call_idをVonage APIに送信するだけです。APIはIDベースのルックアップでも date_startを必要とし、それがないと422を返す。デフォルトの isoDaysAgo(7)を追加することで解決した。

4.UXの反復

データが正しく流れるようになったら、ダッシュボードを便利で楽しいものにする、という楽しい部分に取り掛かった！それは、ダッシュボードを便利で楽しいものにすることだった：

• ページネーション

  • 最初のテーブルでは、すべての結果が一度にダンプされた。何百ものレコードがある場合、これは使い物にならなかった。Prev/Nextコントロールで1ページあたり10レコードのページネーションを追加することで、ナビゲートできるようになった。

• カラーKPIカード

  • ステータス別にレコードをカウントするシンプルなものでも構わない。色分けされたカードなら、番号をスキャンしなくても、一目でステータスの内訳を読み取ることができる。

• クリック・ツー・フィルター

  • KPIカードをクリックできるようにし、"Status: rejected "をタップすると、その行だけにフィルタリングされるようにしたことで、サマリーが装飾的なものから機能的なものに変わった。

  • AIエージェントのおかげでコーディングがとても簡単になった！この小さな追加機能によって、小さなデモが本当に素敵で楽しいものになった。

• Voiceタブの再構築

  • 元の「Voice」タブは、コールIDを貼り付けると詳細が表示される、単一の入力フィールドでした。これは、探している通話がすでに分かっている場合にのみ機能する。インシデント発生時には、そうはいきません。

  • タブをSMSのパターンに合わせて一から作り直した。まず、日付範囲とフィルターが表示され、通話をブラウズできるリストが表示され、次にクリックすると個々の通話の詳細パネルが表示される。これにより、検索ツールから調査ツールに変わった。

これらの変更はすべて、ダッシュボードを実際に使ってみて、どこがおかしいか気づいたことから生まれました。コーディングエージェントがUI開発プロセスをアシストしてくれるので、小さなステップを踏んで、ひとつひとつをテストし、美しいものを作り上げるまで反復するのはとても楽しいことです！

結論

Vonage Reports MCP Appは、MCP Appがダッシュボード・スタイルのUIをClaudeにどのようにもたらすかを示しています。基本的なレポーティングは本番環境でも可能で、拡張することもできます：

• チャートを追加して、通話ステータスの経時変化を確認できます。

• CSVエクスポート

  • 本来、CSVはダウンロードできるはずだった。しかし、そのために必要なAPIはクロードの組み込みブラウザによってブロックされている。アプリに不必要な複雑さを加えたくなかったので、このデモではテキストのソリューションで十分だった。

• リアルタイム更新

  • インターバルでAPIをポーリングし、ライブ統計をストリーミングする。

• カスタムアラート

  • 異常なパターン（故障の急増、異常なコスト）を強調し、Vonage Tooling Serverを使用してテキスト、RCS、または電話アラートを送信します。

完全なソースコードは GitHubで公開されており、ビルド済みリリースは5分でダウンロードして実行できる。フォークして修正し、ビルドしたものを私たちに教えてください！