Créer un tableau de bord de rapports dans Claude Desktop avec MCP Apps et Vonage

Dans ce tutoriel, vous allez créer un tableau de bord de reporting en temps réel dans Claude Desktop.

Introduction

"Le SMS est en panne".

C'est la seule information que vous recevez de votre équipe. Pas de détails. Pas de journaux.

S'agit-il d'un problème régional ? Un problème lié à l'opérateur ? Un bogue dans votre application ? Pour répondre à ces questions, il faut généralement passer d'un tableau de bord à l'autre, exporter des rapports et évaluer manuellement les données. Ou alors, vous êtes malin et vous écrivez rapidement des scripts pour vérifier l'API. Quoi qu'il en soit, ce n'est pas rapide. Et ce n'est certainement pas ce que vous voulez faire sous pression.

Et si vous pouviez enquêter sur tout cela directement dans le chat que vous utilisez tous les jours ?

C'est ce que permettent les applications de protocole de contexte de modèle (MCP). Considérez-les comme le moment de l'interface graphique pour les outils d'IA. De la même manière que les interfaces graphiques ont rendu l'informatique accessible à d'autres spécialistes, les MCP Apps apportent une réelle interactivité aux outils MCP que vous connectez à vos agents d'IA.

Dans ce billet, vous apprendrez à créer un tableau de bord de rapports qui fonctionne dans Claude Desktop en utilisant le cadre MCP Apps. Il se connecte à la Reports API de Vonage et transforme les enregistrements bruts en une interface utilisateur interactive qui vous permet de comprendre ce qui se passe en temps réel.

>> TL;DR : Passez à l'étape suivante et trouvez le quickstart et le code de l'application sur GitHub.

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

Conditions préalables

Avant de commencer, assurez-vous que vous disposez des informations nécessaires :

• Bureau de Claude

• Un compte API Vonage

• Node.js 18+

  • nécessaire uniquement si vous construisez à partir des sources ; la version préconstruite n'en a pas besoin

Comment fonctionne notre application MCP

MCP Apps vs. MCP Servers

Si vous connaissez le Model Context Protocolvous connaissez les serveurs MCP. Ils étendent les capacités d'un agent d'intelligence artificielle en lui fournissant des outils et des ressources. Le MCP Tooling Serverpar exemple, expose des points d'extrémité tels que send_sms ou get_records_report que Claude peut appeler en votre nom.

Les MCP Apps sont différentes. Il s'agit de serveurs MCP qui intègrent également une interface utilisateur interactive directement dans un agent d'intelligence artificielle. Cela signifie que vous avez accès à des boutons, des filtres, des formulaires et des éléments d'interface utilisateur complexes.

Les applications MCP sont vraiment utiles lorsqu'une réponse en texte simple ne suffit pas. Si vous explorez de grands ensembles de données, si vous configurez des systèmes à entrées multiples, si vous surveillez l'activité en direct ou si vous passez par des flux de travail à plusieurs étapes, une interface utilisateur interactive rend ces tâches plus rapides et plus faciles à raisonner. Au lieu d'une conversation à bâtons rompus, les utilisateurs peuvent tout voir en même temps et interagir directement.

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

Comment le système fonctionne-t-il ?

Voici ce qui se passe lorsque vous exécutez un rapport :

1. Vous interagissez avec le tableau de bord à l'intérieur de Claude

2. Le tableau de bord appelle un outil sur le serveur MCP App

3. Le serveur appelle le serveur MCP de Vonage en amont.

4. Le serveur MCP de Vonage utilise l'API Reports de Vonage.

5. Les données remontent le long de la chaîne

6. Le serveur le normalise et le masque, puis le renvoie à l'interface utilisateur.

7. Le tableau de bord affiche les résultats en ligne

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

Votre serveur sert de pont entre les données brutes de l'API et une interface interactive. Il normalise la réponse de l'API Vonage, masque les numéros de téléphone sensibles avant de les afficher et structure les données à consommer par l'interface utilisateur.

Comment c'est assemblé

1. Le serveur (src/serveur.ts)

   Le serveur enregistre deux outils (sms_report et voice_report) et fait office de mandataire entre l'interface utilisateur et Vonage. Plutôt que d'appeler l Reports API de Vonage de Vonage, il enveloppe le serveur Tooling MCP existant en tant que sous-processus, l'appelle en votre nom et normalise la réponse pour l'afficher. get-records-report en votre nom, et normalise la réponse pour l'affichage. L'implémentation est ainsi allégée : l'authentification, la signature des demandes et la gestion des erreurs restent dans le serveur MCP de Vonage. Notre serveur se contente de mettre en forme les données et de les transmettre à l'interface utilisateur.

2. L'interface utilisateur (src/ui/mcp-app.ts)

   Il génère notre tableau de bord HTML interactif. Il crée des sélecteurs de date, des filtres d'état, des tableaux paginés et des détails de ligne extensibles en les regroupant dans un seul fichier autonome via la fonction Vite vite-plugin-singlefile. Le rendu se fait à l'intérieur de Claude car chaque enregistrement d'outil inclut un pointeur vers lui :

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

   Copie

   Lorsque Claude Desktop voit ces métadonnées, il rend l'interface en ligne au lieu de renvoyer du texte brut. A partir de là, l'interface utilisateur gère tout ce qui est côté client : l'appel à app.callServerTool() pour récupérer les données, le suivi de la pagination et des filtres actifs, et la gestion du clic vers le filtre sur les cartes KPI et l'expansion des lignes pour les détails du message et de l'appel.

3. Sécurité des données

   Les numéros de téléphone sont masqués sur le serveur avant que les données n'atteignent l'interface utilisateur. Les quatre derniers chiffres sont conservés, le reste est remplacé. Cela signifie que les exportations, les captures d'écran et les copies du presse-papiers ne laisseront pas échapper les numéros complets, même accidentellement.

Installation en 5 minutes

Étape 1 : Télécharger la version

Rendez-vous sur la page page des versions GitHub et téléchargez vonage-reports-mcp-app-v0.1.0.tar.gz. Extrayez-le dans un dossier sur votre machine (par exemple, ~/vonage-reports-app/).

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

Étape 2 : Ajouter à Claude Desktop Config

Ouvrez votre claude_desktop_config.json

• Il se trouve à l'adresse ~/Library/Application Support/Claude/ sur macOS, ou %APPDATA%\Claude\ sous Windows

• Ajouter cette entrée à l'objet mcpServers objet :

{
  "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"
    }
  }
}

• Remplacez les chemins d'accès et les informations d'identification par vos valeurs réelles.

  • Vous pouvez trouver vos informations d'identification API dans vos Paramètres de l'API de Vonage.

Étape 3 : Redémarrer Claude Desktop

Fermez complètement Claude et rouvrez-le. L'application MCP s'initialisera au démarrage.

Étape 4 : Ouvrir le tableau de bord

Dans Claude, recherchez le tableau de bord Vonage Reports dans la section MCP Apps. Vous devriez voir deux onglets : Rapport SMS et Rapport Voice. Vous êtes prêt à partir !

Exécutez votre premier rapport

Pour déclencher l'interface utilisateur, vous devez appeler l'outil à l'aide d'une invite telle que, "Exécuter le rapport SMS".. Vous aurez alors accès au formulaire et au tableau de bord.

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

Rapport sur les SMS

1. Définissez votre fourchette de dates

   • Utilisez les sélecteurs de date et d'heure pour sélectionner une plage (par exemple, les 7 derniers jours).

2. Filtre par statut (optionnel)

   • Cliquez sur le menu déroulant "Statut" et choisissez une valeur telle que "délivré", "échoué" ou "rejeté".

3. Filtrer par expéditeur ou destinataire (facultatif)

   • Saisissez les numéros de téléphone au format E.164 (par exemple, +12025550123).

4. Inclure le contenu du message (facultatif)

   • Cochez cette case si vous voulez voir les corps de SMS réels dans les résultats. (⚠ Attention : les corps des messages peuvent contenir des informations privées)

5. Cliquez sur "Exécuter le rapport".

   • Le tableau de bord récupère vos enregistrements et les affiche.

Ce que vous verrez

• Cartes KPI

  • En haut, des cartes d'état colorées indiquent la répartition de vos messages :

    • Vert = Livré

    • Rouge = Échec ou rejet

    • Jaune = soumis, accepté ou mis en mémoire tampon

    • Gris = expiré, supprimé ou inconnu

  • Cliquez sur n'importe quelle carte pour filtrer le tableau sur ces lignes uniquement. Cliquez à nouveau pour effacer le filtre.

• Tableau paginé

  • Le tableau des résultats affiche 10 enregistrements par page avec des colonnes telles que date, de, à, statut, réseau, pays et prix. Les valeurs longues (comme les ID de référence internes) sont tronquées par une infobulle au survol.

• Messages extensibles

  • Si vous avez activé l'option "Inclure le contenu des messages", les lignes contenant le corps des messages afficheront un bouton ▶ msg. Cliquez dessus pour développer et voir le texte complet du message.

• Copier CSV

  • Cliquez sur le bouton "Copier CSV" pour exporter les résultats actuels dans votre presse-papiers. Collez-les dans un tableur ou un éditeur de texte.

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

Rapport Voice

L'onglet Rapport Voice fonctionne de la même manière. Choisissez une plage de dates, filtrez éventuellement par statut ou par direction d'appel (entrant/sortant) et exécutez le rapport. Les résultats indiquent le début des appels, leur durée, les numéros de départ et d'arrivée, le statut, etc. Cliquez sur le bouton ▶ sur n'importe quelle ligne pour afficher tous les champs disponibles pour cet appel.

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

Comment il a été construit

Cette application MCP a été construite en utilisant des agents d'intelligence artificielle (en commençant par GPT 5.2 dans Windsurf et en passant ensuite à Claude Code dans Claude Desktop), de sorte qu'un tutoriel étape par étape est un peu difficile avec le codage probabiliste. Comme toute application, celle-ci n'a pas été construite de manière linéaire et propre. Elle est passée par quatre phases principales que je décris ci-dessous.

Configuration du projet

En plus de Claude Code, je devais donner à l'agent quelques ressources :

• Installer la compétence MCP Apps skill

• Le serveur d'outils MCP Tooling Server et serveurs de documentation

La compétence MCP Apps permet à l'agent de comprendre comment construire une application MCP. Le serveur Tooling permet à l'agent d'accéder à l'outil get-records-report qui appelle l'API Reports. Enfin, le serveur de documentation aide l'agent à comprendre exactement comment fonctionnent les API de Vonage et à utiliser la documentation la plus récente au lieu d'halluciner des réponses ou d'utiliser une vieille documentation provenant de ressources Internet.

1. Planifier avec l'IA

Le projet a débuté par une simple demande :

"Je veux créer une application MCP intéressante et significative pour le blog des développeurs de Vonage en utilisant la fonction get-records-report du serveur MCP de Vonage. Quelque chose comme : 'Pouvez-vous obtenir un rapport de tous les SMS sortants envoyés au cours de la dernière semaine?' 'Pouvez-vous obtenir le rapport pour l'ID d'appel vocal 1234-abcd-5678-efgh?'

Pourriez-vous m'aider à définir comment construire une telle application ?"

À partir de là, le GPT 5.2 a posé une série de questions sur le champ d'application :

• Dans quelle mesure les fonctionnalités doivent-elles être perfectionnées ? S'agit-il d'une simple démo ou de quelque chose de presque prêt pour la production ?

• Comment relier l'interface utilisateur à la couche de données ?

• Comment traiter les informations personnelles identifiables (IPI) dans le contenu des messages ? Par exemple, les numéros de téléphone et le contenu des messages.

Après avoir répondu à toutes ces questions, l'agent était prêt avec un plan de mise en œuvre complet qui définissait l'architecture, la structure de l'interface utilisateur à deux onglets, le modèle de proxy et les valeurs par défaut de la sécurité des données. Lire l'intégralité du plan initial.

2. Le faire fonctionner

La première version a été construite en planche à voile. Mais je n'arrivais pas à faire fonctionner l'application dans le chat. J'ai essayé de passer à Cursor et VS Code. Théoriquement, les applications MCP fonctionnent dans tous ces environnements. Mais j'ai passé beaucoup plus de temps à essayer de comprendre cela qu'il n'en a fallu pour créer l'application elle-même.

L'environnement par défaut dans lequel les applications MCP rendent leur interface utilisateur est Claude Desktop. Je l'ai donc téléchargé. Après avoir configuré mes identifiants Vonage correctement, cela a fonctionné immédiatement ! Le tableau de bord est apparu du premier coup.

Si vous créez une application MCP, testez-la dans Claude Desktop dès le premier jour. Ne vous battez pas contre l'environnement.

3. Débogage

Une fois l'application exécutée dans Claude Desktop, il restait quatre problèmes à résoudre au niveau du code. C'est là que le serveur MCP de Vonage Docs s'est avéré très utile, car l'agent a pu rapidement trouver où il avait fait des suppositions erronées sur le comportement des applications Vonage ou MCP.

1. Le premier problème était que le contenu structuré n'était jamais alimenté. Le cadre ext-apps (MCP Apps) exige que les outils renvoient un champ structuredContent avec la réponse textuelle. Mais le serveur MCP de Vonage ne renvoie pas structuredContent comme champ. Il renvoie tout sous la forme d'une chaîne JSON intégrée dans le fichier content[0].text. Le serveur lisait res.structuredContentet obtenait une valeur non définie, et la validation du cadre échouait. La solution a été une extractStructured() qui lit le champ texte et l'analyse à la place.

2. La réponse de Vonage comporte un préfixe lisible par l'homme. Même après avoir corrigé le structuredContent problème, JSON.parse() échouait toujours. Le texte brut du serveur Vonage ressemble à ceci :
   
   

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

   Copie

   Un simple JSON.parse() sur cette chaîne échoue à cause du préfixe. La solution a été une regex pour extraire uniquement le bloc JSON avant l'analyse.

3. Non-concordance du type de schéma entre l'outil de rapport vocal et MCP Apps

   
   L'outil Voice outputSchema utilisé z.record() au niveau de la racine. Le cadre ext-apps nécessite z.object() — z.record(), ce qui a provoqué un plantage (Cannot read properties of undefined (reading '_zod')). Il s'agit d'un petit changement, mais le message d'erreur ne le rendait pas évident.

4. Paramètre requis manquant sur les appels vocauxL'outil vocal d'origine a seulement envoyé call_id à l'API de Vonage. L'API exige un paramètre date_start même pour les recherches basées sur l'ID et renvoie un 422 sans ce paramètre. L'ajout d'un paramètre par défaut de isoDaysAgo(7) a permis de résoudre ce problème.

4. Rétroaction sur l'interface utilisateur

Une fois que les données ont circulé correctement, je suis passé à la partie la plus amusante : rendre le tableau de bord utile et agréable à utiliser ! Cela s'est fait par petites étapes :

• Pagination

  • La table initiale affichait tous les résultats en une seule fois. Avec des centaines d'enregistrements, il était inutilisable. L'ajout d'une pagination de 10 enregistrements par page avec des contrôles Précédent/Suivant l'a rendu navigable.

• Cartes KPI en couleur

  • Un simple décompte des enregistrements par statut est suffisant. Les cartes à code couleur vous permettent de lire la répartition par statut d'un seul coup d'œil sans avoir à scanner les numéros.

• Cliquer pour filtrer

  • Le fait de rendre les fiches ICP cliquables, de sorte que le fait d'appuyer sur "Statut : rejeté" filtre le tableau sur ces lignes uniquement, a transformé le résumé de décoratif en fonctionnel.

  • Il s'agit d'une fonction bonus que j'aurais probablement ignorée avant que AI Agents ne rende le codage tellement plus facile ! Cette petite fonctionnalité supplémentaire m'a rendu très heureux, transformant une petite démo en quelque chose de vraiment sympa/amusant.

• Remaniement de l'onglet Voice

  • L'onglet Voice original ne comportait qu'un seul champ de saisie : collez un numéro d'appel et obtenez les détails en retour. Cela ne fonctionne que si vous savez déjà quel appel vous recherchez. Ce n'est pas le cas lors d'un incident.

  • L'onglet a été entièrement reconstruit pour correspondre au modèle de SMS : une plage de dates + des filtres d'abord, une liste d'appels à parcourir, puis un panneau de détails à développer d'un clic pour chaque appel individuel. L'onglet est ainsi passé d'un outil de recherche à un outil d'investigation.

Chacun de ces changements est le fruit de l'utilisation du tableau de bord et de l'observation de ce qui n'allait pas. Grâce aux agents de codage qui assistent le processus de développement de l'interface utilisateur, il est tellement agréable de procéder par petites étapes, de tester chaque chose, puis d'itérer jusqu'à ce que vous ayez construit quelque chose de magnifique !

Conclusion

L'application MCP Vonage Reports montre comment les applications MCP apportent des interfaces utilisateur de type tableau de bord à Claude. Elle est prête pour la production de rapports de base et vous pouvez l'étendre :

• Ajoutez des graphiques pour voir comment le statut de votre appel évolue dans le temps.

• Exporter vers CSV

  • A l'origine, le CSV devait pouvoir être téléchargé. Mais l'API nécessaire pour ce faire est bloquée par le navigateur intégré de Claude. Je n'ai pas voulu ajouter de complexité inutile à l'application, donc la solution textuelle a bien fonctionné pour cette démo.

• Mises à jour en temps réel

  • Interroger l'API à intervalles réguliers et diffuser des statistiques en direct

• Alertes personnalisées

  • Mettez en évidence les schémas inhabituels (pic de défaillances, coûts inhabituels), puis utilisez le Vonage Tooling Server pour envoyer un texte, un RCS ou un appel téléphonique d'alerte.

Le code source complet est disponible sur GitHubet la version pré-construite est prête à être téléchargée et exécutée en 5 minutes. Faites-le, modifiez-le, et faites-nous savoir ce que vous construisez !