Servidor MCP de telefonía para inteligencia artificial y modelos lingüísticos

Introducción al MCP (Protocolo Modelo-Contexto)

El Protocolo Modelo-Contexto (MCP) es una especificación que permite a los grandes modelos lingüísticos (LLMS) descubrir y utilizar herramientas y servicios externos. Se trata de un lenguaje universal que permite a los LLM comunicarse con API, bases de datos y otras aplicaciones de forma estandarizada.

En este tutorial, aprenderá a crear herramientas MCP que pueden integrarse con cualquier aplicación Agentic AI (como Claude Desktop, Github Copilot o Cursor) y pueden realizar llamadas, enviar SMS y recoger las respuestas para mostrarlas en la aplicación.

>> TL;DR: Puede encontrar el código de trabajo completo en GitHub.

Animated view of Claude’s developer-friendly welcome screen asking, 'How was your day, Mr. Developer?' with contextual mode options like Code, Write, and Learn.

¿Por qué es útil el MCP?

• Extensibilidad: MCP permite a los desarrolladores ampliar las capacidades de los LLM más allá de sus conocimientos incorporados. Mediante la creación de herramientas compatibles con MCP, puedes habilitar un modelo para acceder a información en tiempo real (como previsiones meteorológicas o cotizaciones bursátiles), interactuar con bases de conocimiento privadas o desencadenar acciones en otros sistemas (como enviar un correo electrónico o reservar una reunión).

• Normalización: Proporciona una forma coherente de que los modelos interactúen con las herramientas, independientemente de la implementación subyacente. Esto simplifica el proceso de desarrollo tanto para los creadores de herramientas como para los desarrolladores de modelos.

• Seguridad y control: MCP permite un control granular sobre las herramientas a las que puede acceder un modelo, garantizando que el modelo sólo realiza las acciones para las que está autorizado.

Requisitos previos

• Conocimientos de Python: Conocimientos intermedios del lenguaje de programación Python y Python v3.13+.

• Escritorio Docker: La aplicación se ejecutará en un entorno de contenedores y utiliza Docker Compose.

• Claude Desktop Aplicaciones: Este tutorial utiliza Clause, pero cualquier aplicación de IA agéntica, como Cursor, Windsurf o GitHub Copilot que viene con VSCode, también puede funcionar.

• Cuenta API de Vonage: Para realizar llamadas y comunicarse con SMS, se necesita una cuenta de Vonage. Esto incluye una clave API, un secreto API, un número virtual largo y una aplicación de voz que se puede crear desde el panel de Vonage.

• Proxy inverso Ngrok: Para actuar como Webhook para recoger eventos como el progreso de la llamada y SMS entrantes.

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls—all at your fingertips.

Cómo funciona MCP: Un ejemplo de herramienta meteorológica

Para entender cómo funciona MCP, consideremos un ejemplo sencillo: un servidor meteorológico. La interacción está gestionada por un Cliente MCPque se ejecuta localmente como un plugin de la aplicación LLM o Agentic AI. Este cliente se encarga de comunicarse con el servidor MCP remoto.

1. Pregunta del usuario: Un usuario pregunta al LLM: "¿Qué tiempo hace en Londres?".

2. LLM a Cliente MCP: El LLM entiende la intención del usuario y utiliza su plugin local de Cliente MCP para encontrar una herramienta adecuada.

3. Descubrimiento de herramientas (Cliente -> Servidor): El Cliente MCP envía una petición al Servidor MCP para descubrir las herramientas disponibles.

4. Selección de herramientas: El servidor MCP responde con una lista de herramientas, incluyendo get_weather(ubicación: str). El LLM, a través del cliente, selecciona esta herramienta.

5. Invocación de la herramienta (Cliente -> Servidor): El Cliente MCP envía una petición al Servidor MCP para ejecutar la herramienta obtener_tiempo con el parámetro location="Londres".

6. Ejecución: El servidor MCP recibe la solicitud, ejecuta la función subyacente (que a su vez llama a una API meteorológica) y obtiene el tiempo actual en Londres.

7. Respuesta (Servidor -> Cliente -> LLM): El servidor envía el resultado (por ejemplo, "El tiempo en Londres es de 15°C y está nublado.") de vuelta al Cliente MCP, que a su vez lo pasa al LLM.

8. Respuesta final: El LLM formatea esta información en una respuesta fácil de usar y la presenta al usuario.

Este flujo de trabajo demuestra cómo el Cliente MCP actúa como puente local, mientras que el Servidor MCP proporciona la funcionalidad real de la herramienta, creando una conexión perfecta entre el modelo lingüístico y las capacidades externas.

Sequence diagram showing how a user query about London's weather flows through an LLM, MCP Client, MCP Server, and Weather API to return a response.

¿Qué es un servidor MCP de telefonía?

El Servidor MCP de Telefoníar es un servidor basado en Python que expone las funcionalidades de comunicación de Vonage como un conjunto de herramientas a través del Protocolo Modelo-Contexto. Actúa como intermediario, traduciendo las solicitudes de un modelo de lenguaje en llamadas API a la plataforma de Vonage y devolviendo los resultados.

Este servidor MCP aprovecha el conjunto de API de comunicación de Vonage. Estas API te permiten programar llamadas telefónicas, enviar mensajes como RCS, SMS, WhatsApp, crear aplicaciones de video WebRTC y mucho más.

Construir sobre estas API permite a un modelo de lenguaje, como Claude, realizar acciones de telefonía como realizar llamadas y enviar mensajes de texto simplemente utilizando las herramientas proporcionadas por el servidor.

Lista de herramientas de Vonage en el servidor MCP de telefonía

El servidor MCP de telefonía incluye un conjunto de herramientas predefinidas para las tareas habituales de telefonía:

• voice_call(to: str, message: str, from_: str = "VONAGE_LVN"): Inicia una llamada de voz a un número especificado y transmite un mensaje.

• send_sms(to: str, text: str, from_: str = "VONAGE_LVN"): Envía un mensaje SMS a un número especificado.

• check_call_status(call_uuid: str = None): Comprueba el estado de una llamada específica o enumera todas las llamadas activas.

• voice_call_with_input(to: str, prompt_message: str, from_: str = "VONAGE_LVN", wait_for_result: bool = True): Realiza una llamada de voz, reproduce un mensaje y utiliza el reconocimiento de voz para capturar la respuesta del destinatario.

• sms_with_input(to: str, text: str, from_: str = "VONAGE_LVN", wait_for_result: bool = True): Envía un mensaje SMS y espera la respuesta del destinatario.

Cómo funciona la herramienta send_sms

Recorramos el proceso de uso de la función send_sms con un modelo de lenguaje como Claude, que interactúa con el servidor a través de un Cliente MCP.

1. Usuario: "Oye Claude, ¿puedes enviar un mensaje a mi amigo al +1-202-555-0183 y decirle que llego 10 minutos tarde a nuestra reunión?".

2. Claude (LLM): Entiende la intención del usuario de enviar un SMS. Sabe por su integración MCP que un enviar_sms está disponible.

3. Claude (Uso de la Herramienta a través del Cliente MCP): A través de su Cliente MCP local, Claude realiza una petición al Servidor MCP de Telefonía, invocando el comando enviar_sms con los parámetros:

   • a: "+12025550183"

   • texto: "Hola, llego 10 minutos tarde a nuestra reunión".

4. Servidor MCP de telefonía: Recibe la solicitud del cliente MCP. Luego crea y envía una solicitud de API a la SMS API de Vonage con los detalles provistos.

5. API de Vonage: Procesa la solicitud y envía el mensaje SMS al teléfono del destinatario. Luego devuelve un estado de éxito al servidor MCP de telefonía.

6. Servidor MCP de telefonía al cliente: El servidor formatea el estado de éxito de Vonage y lo envía de vuelta al cliente MCP.

7. Claude (Respuesta): El Cliente MCP pasa la confirmación de éxito a Claude, que informa al usuario: "Ok, he enviado el mensaje a tu amigo."

Sequence diagram illustrating how Claude uses MCP and the Vonage SMS API to send a message on behalf of a user.

Cómo configurar el servidor MCP de telefonía

Paso 1: Clonar el repositorio

git clone https://github.com/Vonage-Community/telephony-mcp-server
cd telephony-mcp-server

Paso 2: Abrir un túnel ngrok

Para recibir webhooks de Vonage, tu servidor local debe ser accesible a través de Internet. Usa ngrok para exponer tu servidor, abre una nueva pestaña en tu terminal y ejecuta:

ngrok http 8080

El resultado será algo parecido a esto:

Session Status                online
Version                       3.22.1
Forwarding                    https://4cc705fd88d9.ngrok.app -> http://localhost:8080

En el ejemplo anterior, ngrok ha creado y asignado un nombre de dominio accesible en Internet https://4cc705fd88d9.ngrok.appque puede reenviar el tráfico al servidor de devolución de llamada alojado localmente en el puerto 8080. Lo utilizaremos en el archivo de configuración .env como:

CALLBACK_SERVER_URL=https://4cc705fd88d9.ngrok.app

Puede leer más sobre pruebas con ngrok en nuestro portal de herramientas para desarrolladores.

Paso 3: Crear una aplicación de Vonage

Inicia sesión en Vonage Developer Dashboard y crea una nueva aplicación. Genera y descarga una clave privada y colócala en la raíz del directorio del proyecto. Se copiará en el contenedor Docker.

Active las funciones Voice y Messages, como se muestra a continuación. También tendrá que configurar los puntos finales webhook para cada capacidad; sin embargo, ya que en realidad no vamos a utilizar estos puntos finales, puede simplemente añadir marcadores de posición.

Para Voice:

• URL de respuesta: https://4cc705fd88d9.ngrok.app/ncco

• URL del evento: https://4cc705fd88d9.ngrok.app/event

Para mensajes:

• URL de entrada: https://4cc705fd88d9.ngrok.app/event

• URL de estado: https://4cc705fd88d9.ngrok.app/event

Creating a Vonage application for a Telephony MCP Server in the Vonage API Dashboard, showing the configuration of Voice and Messages capabilities, webhook URLs, and key generation.

Paso 4: Añadir Webhook de entrada para recibir SMS

Desde el panel para desarrolladores de Vonage, ve a Tus Numbers y edita el número que deseas usar haciendo clic en el ícono del lápiz. En la sección "Inbound Webhook URL" de la ventana de configuración, agrega la url de ngrok junto con "/event", por ejemplo https://4cc705fd88d9.ngrok.app/event.

Configuring the inbound SMS webhook URL for a Vonage virtual number in the Dashboard under 'Your Numbers' settings.

Una vez guardada la configuración, cualquier SMS enviado al número virtual anterior se reenviará a https://4cc705fd88d9.ngrok.app/event

Paso 5: Agrega tus credenciales de Vonage

Cree un archivo llamado .env en la raíz del proyecto.

touch .env

Llénalo con tus credenciales de Vonage:

VONAGE_API_KEY=your_api_key
VONAGE_API_SECRET=your_api_secret
VONAGE_APPLICATION_ID=your_application_id
VONAGE_PRIVATE_KEY_PATH=/app/private.key # Path inside the container
VONAGE_LVN=your_vonage_long_virtual_number
CALLBACK_SERVER_URL=https://<ngrok_generated_url>

Iniciar el servidor MCP de telefonía con Docker

El proyecto utiliza Docker Compose para simplificar la ejecución de los servicios necesarios.

1. Construir e iniciar el contenedor

Desde la raíz del directorio del proyecto, ejecute el siguiente comando:

docker-compose up --build

Este comando lo hará:

1. Cree una única imagen Docker para la aplicación.

2. Inicie un contenedor que ejecute internamente dos servicios: el telephony-mcp-server y el servidor de devolución de llamadacada uno en un puerto diferente.

3. Los servicios se iniciarán en primer plano, lo que le permitirá supervisar sus registros directamente en su terminal.

2. Verify the Servers are Running (Verificar que los servidores están funcionando)

• El servidor MCP de telefonía estará disponible en http://localhost:8000.

• El servidor de devolución de llamada se ejecutará en http://localhost:8080.

Integración del servidor MCP de telefonía con Claude

Puede integrar el Servidor MCP de Telefonía con Claude a través de clientes que soporten MCP, como la aplicación Claude Desktop.

• Abra la configuración de escritorio de Claude: Navegue a Claude > Settings > Developer > Edit Config para abrir claude_desktop_config.json para abrir el archivo claude_desktop_config.json.

Step-by-step instructions to access and edit the Claude desktop MCP configuration file via Developer Settings.

• Añadir configuración del servidor MCP de telefonía: Introduzca el siguiente json en claude_desktop_config.json:

{
  "mcpServers": {
    "telephony": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:8000/mcp"
      ]
    }
  }
}

Guarde el archivo json, salga y reinicie Claude para que los cambios surtan efecto.

• Valide que Claude está conectado: Vaya a Claude > Configuración > Desarrollador. Debería haber una entrada "telefonía" con el estado "en ejecución".

Claude's Developer settings showing the 'telephony' tool actively running with an MCP remote endpoint configured via NPX.

Ejecutar las herramientas MCP en Claude Desktop

Una vez integrado, puede empezar a dar órdenes a Claude que utilicen las herramientas de telefonía. Puedes comprobar la disponibilidad de Herramientas desde el menú 'Búsqueda y Herramientas':

Screenshot showing Claude’s prompt interface with MCP tools like send_sms and voice_call enabled via the tools menu.

Imagina que quieres preguntar a un amigo si está libre para cenar. Prueba a enviar a Claude la siguiente pregunta "Envía un mensaje a Jane al +1-202-555-0125 y pregúntale si está libre para cenar esta noche".

Claude reconocerá la intención y la herramienta necesaria. Puede que te muestre una confirmación antes de ejecutar:

Tool: send_sms
to: "+12025550125"
text: "Hi Jane, are you free for dinner tonight?"

[Execute] [Cancel]

Después de que lo apruebes, Claude utilizará la herramienta y te dará una confirmación final:

"He enviado el mensaje a Jane."

Más adelante, podrías utilizar otra herramienta:

"Llama a Jane para ver si recibió mi mensaje".

Y Claude utilizaría la función llamada_de_voz para conectarte.

Conversation with Claude using the sms_with_input MCP tool to send and follow up on a message asking if someone likes ice cream.

Conclusión y observaciones finales

El Servidor MCP de Telefonía es un poderoso ejemplo de cómo el Protocolo Modelo-Contexto puede tender un puente entre los modelos lingüísticos avanzados y las acciones del mundo real. Al proporcionar una forma estandarizada para que los LLM accedan a las API de comunicación, desbloqueamos una nueva clase de aplicaciones en las que los asistentes de IA pueden interactuar con el mundo en nuestro nombre de una forma significativa y tangible.

Este proyecto no sólo sirve como herramienta práctica, sino también como modelo para ampliar las capacidades de los modelos lingüísticos a cualquier dominio que disponga de una API. Las posibilidades sólo están limitadas por nuestra imaginación.

¿Tienes preguntas o comentarios sobre este tutorial? Descarga el código y otros proyectos increíbles de Vonage-Comunidad. Siempre agradecemos la participación de la comunidad. Comparte tus opiniones con nosotros en X (antes Twitter) o únete a la discusión en nuestro canal Slack de la comunidad de Vonage citando este artículo para obtener una respuesta rápida. También puedes conectarte conmigo conmigo en Twitter.