Crea un panel de informes en Claude Desktop con MCP Apps y Vonage

En este tutorial, creará un panel de informes en tiempo real dentro de Claude Desktop.

Introducción

"SMS no funciona".

Esa es toda la información que recibes de tu equipo. Sin detalles. Sin registros.

¿Es un problema regional? ¿Un problema del operador? ¿Un error en la aplicación? Responder a estas preguntas suele implicar saltar entre paneles de control, exportar informes y evaluar manualmente los datos. O puede que seas listo y escribas rápidamente algunos scripts para comprobar la API. En cualquier caso, no es rápido. Y definitivamente no es lo que quieres hacer bajo presión.

¿Y si pudieras investigar todo eso directamente dentro del chat que utilizas a diario?

Eso es lo que hacen posible las aplicaciones del protocolo de contexto de modelo (MCP). Piense en ellas como el momento GUI para las herramientas de IA. De la misma manera que las interfaces gráficas hicieron accesible la informática más allá de los especialistas, las aplicaciones MCP aportan interactividad real a las herramientas MCP que conectas a tus agentes de IA.

En esta publicación, aprenderás a crear un panel de informes que se ejecuta dentro de Claude Desktop usando el framework MCP Apps. Se conecta a la API de informes de Vonage y convierte los registros sin procesar en una interfaz de usuario interactiva que te permite comprender lo que sucede en tiempo real.

>> TL;DR: Saltar adelante y encontrar el quickstart y el código de la aplicación en GitHub.

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

Requisitos previos

Antes de empezar, asegúrate de que tienes:

• Claude Escritorio

• Una cuenta API de Vonage

• Node.js 18+

  • sólo es necesario si se compila a partir del código fuente; la versión precompilada no lo requiere

Cómo funciona nuestra aplicación MCP

Aplicaciones MCP frente a servidores MCP

Si está familiarizado con el Protocolo de Contexto de Modeloya conoce los servidores MCP. Amplían las capacidades de un Agente de IA proporcionándole herramientas y recursos. El Servidor de herramientas MCPpor ejemplo, expone puntos finales como send_sms o get_records_report que Claude puede llamar en su nombre.

Las aplicaciones MCP son diferentes. Son servidores MCP que también incluyen una interfaz de usuario interactiva directamente dentro de un agente AI. Esto significa que tiene acceso a botones, filtros, formularios y elementos de interfaz de usuario complejos.

Las aplicaciones MCP son realmente útiles cuando una respuesta en texto plano no es suficiente. Si está explorando grandes conjuntos de datos, configurando sistemas con múltiples entradas, supervisando la actividad en directo o recorriendo flujos de trabajo de varias etapas, una interfaz de usuario interactiva agiliza esas tareas y facilita el razonamiento. En lugar de una conversación de ida y vuelta, los usuarios pueden ver todo a la vez e interactuar con ello directamente.

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

Cómo funciona el sistema

Esto es lo que ocurre cuando ejecutas un informe:

1. Interactúas con el salpicadero dentro de Claude

2. El cuadro de mandos llama a una herramienta del servidor MCP App

3. El servidor llama al servidor MCP de Vonage ascendente

4. El servidor MCP de Vonage accede a Reports API de Vonage

5. Los datos vuelven a fluir por la cadena

6. El servidor lo normaliza, lo enmascara y lo devuelve a la interfaz de usuario.

7. El cuadro de mandos muestra los resultados en línea

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

Su servidor actúa como puente entre los datos sin procesar de la API y una interfaz interactiva. Normaliza la respuesta de la API de Vonage, enmascara los números de teléfono confidenciales antes de mostrarlos y estructura los datos para que los consuma la interfaz de usuario.

Cómo se monta

1. El servidor (src/servidor.ts)

   El servidor registra dos herramientas (sms_report y voice_report) y actúa como proxy entre la interfaz de usuario y Vonage. En lugar de llamar a la API de Reports de Vonage directamente, envuelve el servidor MCP de herramientas existente como un subproceso, llama get-records-report en tu nombre y normaliza la respuesta para su visualización. Esto mantiene la implementación simplificada: la autenticación, la firma de solicitudes y el manejo de errores permanecen en el servidor MCP de Vonage. Nuestro servidor sólo da forma a los datos y los pasa a la interfaz de usuario.

2. La interfaz de usuario (src/ui/mcp-app.ts)

   Esto genera nuestro panel de control HTML interactivo. Crea selectores de fecha, filtros de estado, tablas paginadas y detalles de fila expandibles agrupándolos en un único archivo autocontenido a través de la función de Vite vite-plugin-singlefile. Se renderiza dentro de Claude porque cada registro de la herramienta incluye un puntero a la misma:

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

   Copia

   Cuando Claude Desktop ve esos metadatos, representa la interfaz en línea en lugar de devolver texto sin formato. A partir de ahí, la interfaz de usuario gestiona todo lo relacionado con el cliente: llamar a app.callServerTool() para obtener los datos, el seguimiento de la paginación y los filtros activos, y la gestión de los clics para filtrar en las tarjetas de KPI y la ampliación de las filas para los detalles de los mensajes y las llamadas.

3. Seguridad de los datos

   Los números de teléfono se enmascaran en el servidor antes de que los datos lleguen a la interfaz de usuario. Se conservan los cuatro últimos dígitos, el resto se sustituye. Esto significa que las exportaciones, capturas de pantalla y copias del portapapeles no filtrarán los números completos, ni siquiera accidentalmente.

Instalar en 5 minutos

Paso 1: Descargar la versión

Vaya a la página de versiones de GitHub y descarga vonage-reports-mcp-app-v0.1.0.tar.gz. Extráelo a una carpeta de tu equipo (por ejemplo, ~/vonage-reports-app/).

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

Paso 2: Añadir a Claude Desktop Config

Abra su claude_desktop_config.json

• Se encuentra en ~/Library/Application Support/Claude/ en macOS, o en %APPDATA%\Claude\ en Windows

• Añade esta entrada al mcpServers objeto:

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

• Sustituya las rutas y las credenciales por sus valores reales.

  • Puedes encontrar tus credenciales de API en Configuración de API de Vonage.

Paso 3: Reinicie Claude Desktop

Cierre Claude completamente y vuelva a abrirlo. La aplicación MCP se iniciará al arrancar.

Paso 4: Abrir el panel de control

En Claude, busca el panel de informes de Vonage en la sección Aplicaciones MCP. Deberías ver dos pestañas: Informe de SMS e Informe de Voice. ¡Estás listo para comenzar!

Ejecute su primer informe

Para activar la interfaz de usuario, tendrá que llamar a la herramienta a través de un prompt como, "Ejecutar el informe SMS".. A continuación, tendrá acceso al formulario y al cuadro de mandos.

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

Informe SMS

1. Establezca su intervalo de fechas

   • Utilice los selectores de fecha/hora para seleccionar un intervalo (por ejemplo, los últimos 7 días).

2. Filtrar por estado (opcional)

   • Haga clic en el menú desplegable "Estado" y elija un valor como entregado, fallido o rechazado.

3. Filtrar por remitente o destinatario (opcional)

   • Introduzca los números de teléfono en formato E.164 (por ejemplo, +12025550123).

4. Incluir el contenido del mensaje (opcional)

   • Marque esta casilla si desea ver los cuerpos reales de los SMS en los resultados. (⚠ Atención: los cuerpos de los mensajes pueden contener información privada)

5. Haga clic en "Ejecutar informe".

   • El panel de control obtiene sus registros y los muestra.

Lo que verá

• Tarjetas KPI

  • En la parte superior, las tarjetas de estado en color muestran el desglose de tus mensajes:

    • Verde = Entregado

    • Rojo = Fallido o rechazado

    • Amarillo = Enviado, Aceptado o Buffered

    • Gris = caducado, borrado o desconocido

  • Haga clic en cualquier tarjeta para filtrar la tabla sólo a esas filas. Haga clic de nuevo para borrar el filtro.

• Tabla paginada

  • La tabla de resultados muestra 10 registros por página con columnas como fecha, desde, hasta, estado, red, país y precio. Los valores largos (como los ID de referencia internos) se truncan con un tooltip al pasar el ratón por encima.

• Mensajes ampliables

  • Si ha activado la opción "Incluir contenido del mensaje", las filas con cuerpos de mensajes reales mostrarán un botón ▶ msg. Haz clic en él para ampliarlo y ver el texto completo del mensaje.

• Copiar CSV

  • Haga clic en el botón "Copiar CSV" para exportar los resultados actuales al portapapeles. Pégalos en una hoja de cálculo o en un editor de texto.

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

Informe Voice

La pestaña Informe de Voice funciona de forma similar. Elija un intervalo de fechas, filtre opcionalmente por estado o dirección de la llamada (entrante/saliente) y ejecute el informe. Los resultados muestran cuándo comenzaron las llamadas, la duración, los números de origen y destino, el estado, etc. Haga clic en el botón ▶ de cualquier fila para ver todos los campos disponibles para esa llamada.

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

Cómo se construyó

Esta aplicación MCP fue construida usando Agentes AI (comenzando con GPT 5.2 en Windsurf y luego pasando a Claude Code en Claude Desktop), por lo que un tutorial paso a paso es un poco difícil con la codificación probabilística. Como cualquier aplicación, esta no fue una construcción limpia y lineal. Pasó por cuatro fases principales que esbozo a continuación.

Configuración del proyecto

Además del Código Claude, necesitaba dar al agente algunos recursos:

• Instalar la habilidad Habilidad MCP Apps

• El servidor de Servidor de herramientas MCP y Servidores de documentación

La habilidad MCP Apps permite al agente entender cómo construir una MCP App. El servidor de herramientas proporciona al agente acceso a la herramienta get-records-report herramienta que llama a la Reports API. Y por último, el servidor de documentación ayuda al agente a comprender exactamente cómo funcionan las API de Vonage y a usar la documentación más actualizada en lugar de alucinar respuestas o usar documentación antigua de recursos de Internet.

1. Planificación con IA

El proyecto se inició con una sola pregunta:

"Quiero crear una aplicación MCP interesante y significativa para el blog de desarrolladores de Vonage utilizando la función get-records-report del servidor MCP de Vonage. Algo como: '¿Puedes obtener un informe de todos los SMS salientes enviados durante la última semana?' '¿Puedes obtener el informe para el ID de llamada de Voice 1234-abcd-5678-efgh?'.

¿Podría ayudarme a esbozar cómo construir una aplicación de este tipo?"

A partir de ahí, el GPT 5.2 planteó una serie de preguntas de alcance:

• ¿Cómo de pulidas deben estar las características? ¿Sólo una demo o algo casi listo para producción?

• ¿Cómo conectar la interfaz de usuario a la capa de datos?

• ¿Cómo tratar la información personal identificable (IPI) en el contenido de los mensajes? Por ejemplo, números de teléfono y contenido de los mensajes.

Tras responder a todas estas preguntas, el Agente estaba listo con un plan de implantación completo que definía por adelantado la arquitectura, la estructura de la interfaz de usuario de dos pestañas, el patrón de proxy y los valores predeterminados de seguridad de los datos. Lea el plan plan inicial.

2. Ponerlo en marcha

La primera versión se construyó en Windsurf. Pero no pude conseguir que la App funcionara dentro del chat. Intenté pasar a Cursor y VS Code. Teóricamente, las aplicaciones MCP funcionan en todos estos entornos. Pero pasé mucho más tiempo tratando de averiguar esto que lo que tomó para crear realmente la aplicación en sí.

El entorno predeterminado de las aplicaciones MCP para mostrar su interfaz de usuario es Claude Desktop. Así que lo descargué. Después de configurar mis credenciales de Vonage correctamente, ¡funcionó de inmediato! El panel de control apareció al primer intento.

Si estás creando una aplicación MCP: pruébala en Claude Desktop desde el primer día. No luches contra el entorno.

3. Depuración

Una vez que la aplicación se ejecutaba en Claude Desktop, había cuatro problemas a nivel de código que resolver. Aquí es donde tener el servidor MCP de Vonage Docs realmente ayudó porque el agente pudo encontrar rápidamente dónde hacía suposiciones incorrectas sobre cómo se comportaban las aplicaciones de Vonage o MCP.

1. El primer problema era que el contenido estructurado nunca se rellenaba. El marco ext-apps (MCP Apps) exige que las herramientas devuelvan un campo structuredContent junto con la respuesta de texto. Pero el servidor MCP de Vonage no devuelve structuredContent como campo. Devuelve todo como una cadena JSON incrustada en content[0].text. El servidor leía res.structuredContentobteniendo undefined, y la validación del framework fallaba. La solución fue un extractStructured() helper que lee el campo de texto y lo analiza en su lugar.

2. La respuesta de Vonage tiene un prefijo legible por humanos. Incluso después de solucionar el structuredContent problema, JSON.parse() seguía fallando. El texto sin procesar del servidor de Vonage tiene este aspecto:
   
   

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

   Copia

   Un simple JSON.parse() en esa cadena falla debido al prefijo. La solución era una regex para extraer sólo el bloque JSON antes de analizarlo.

3. Un tipo de esquema no coincide entre la herramienta de informe de voz y MCP Apps.

   
   La herramienta Voice outputSchema utilizado z.record() en el nivel raíz. El marco ext-apps requiere z.object() — z.record(), lo que provocaba un fallo en tiempo de ejecución (No se pueden leer propiedades de undefined (leyendo '_zod')). Un pequeño cambio, pero no algo que el mensaje de error hiciera obvio.

4. Falta un parámetro obligatorio en las llamadas de vozLa herramienta de voz original sólo enviaba call_id a la API de Vonage. La API requiere un parámetro date_start incluso para las búsquedas basadas en ID y devuelve un 422 sin él. Añadiendo un valor predeterminado de isoDaysAgo(7) lo resolvió.

4. Iterar la experiencia del usuario

Una vez que los datos fluyeron correctamente, llegué a la parte divertida: ¡hacer que el cuadro de mandos fuera útil y divertido de usar! Esto se hizo en pequeños pasos:

• Paginación

  • La tabla inicial volcaba todos los resultados a la vez. Con cientos de registros, era inutilizable. Añadiendo una paginación de 10 registros por página con controles Anterior/Siguiente se pudo navegar.

• Tarjetas KPI en color

  • Un simple recuento de registros por estado está bien. Las tarjetas codificadas por colores permiten leer el desglose del estado de un vistazo sin necesidad de escanear números.

• Haga clic para filtrar

  • Al hacer clic en las tarjetas de KPI, de modo que al pulsar "Estado: rechazado" se filtre la tabla sólo a esas filas, el resumen pasó de ser decorativo a funcional.

  • Esta era una característica extra que probablemente me habría saltado antes de que los Agentes AI hicieran la codificación mucho más fácil. Esta pequeña característica extra me hizo muy feliz, convirtiendo una pequeña demo en algo realmente bonito/divertido.

• Modificación de la pestaña Voice

  • La pestaña Voice original tenía un único campo de entrada: pegar un ID de llamada y obtener los detalles. Esto sólo funciona si ya sabes qué llamada estás buscando. Durante un incidente, no lo sabes.

  • La pestaña se reconstruyó desde cero para adaptarla al patrón de los SMS: primero, un intervalo de fechas y filtros; después, una lista de llamadas por la que se puede navegar y, por último, un panel detallado de llamadas individuales en el que se puede hacer clic para ampliar la información. De este modo, pasó de ser una herramienta de búsqueda a ser una herramienta de investigación.

Cada uno de estos cambios surgió del uso real del panel de control y de darse cuenta de lo que no funcionaba. Con la ayuda de agentes de codificación en el proceso de desarrollo de la interfaz de usuario, es muy agradable ir paso a paso, probar cada cosa e iterar hasta crear algo bonito.

Conclusión

La aplicación Vonage Reports MCP demuestra cómo las aplicaciones MCP llevan las interfaces de usuario estilo tablero a Claude. Está lista para la producción de informes básicos y puedes ampliarla:

• Añade gráficos para ver cómo cambia el estado de tus llamadas a lo largo del tiempo

• Exportar a CSV

  • Originalmente, el CSV debía poder descargarse. Pero la API necesaria para ello está bloqueada por el navegador integrado de Claude. No quería añadir complejidad innecesaria a la aplicación, así que la solución de texto funcionó lo suficientemente bien para esta demo.

• Actualizaciones en tiempo real

  • Sondear la API en un intervalo y transmitir estadísticas en directo

• Alertas personalizadas

  • Resalta patrones inusuales (pico de fallas, costos inusuales) y luego usa el servidor de herramientas de Vonage para enviar una alerta de texto, RCS o hacer una llamada telefónica.

El código fuente completo está disponible en GitHuby la versión precompilada está lista para descargar y ejecutar en 5 minutos. Bifurcalo, modifícalo y cuéntanos lo que has creado.