Paso a paso: Cómo agregar API de Vonage a tu agente de IA con MCP

Introducción

¿Alguna vez ha querido crear su propio chatbot de inteligencia artificial que pueda hacer algo más que responder preguntas? ¿Y si tu chatbot pudiera comprobar el saldo de tu Account, enviar mensajes en tu nombre o interactuar con otros servicios? Eso es exactamente lo que vamos a aprender a construir hoy utilizando Claude API de Anthropic de Anthropic y el nuevo servidor de enlaces de API de protocolo de contexto de modelo (MCP) de Vonage (también conocido como servidor de herramientas).

En este tutorial, crearemos un chatbot que pueda mantener conversaciones contigo y, al mismo tiempo, pueda utilizar herramientas externas; concretamente, lo integraremos con el servidor MCP de Vonage Servidor MCP de herramientas para verificar saldos de Account, por ejemplo.

TL;DR: Puede encontrar el ejemplo de trabajo completo en nuestro repositorio GitHub.

Requisitos previos

Antes de empezar, asegúrate de que tienes:

• Node.js instalado (versión 14 o superior)

• Conocimientos básicos de JavaScript

• Una clave API antrópica

• Una cuenta API de Vonage (para el ejemplo de comprobación de saldo)

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.

Conceptos básicos

¿Qué es la API Claude de Anthropic?

Claude es el asistente de inteligencia artificial de Anthropic que destaca en la comprensión y generación de lenguaje natural. La API le permite integrar las capacidades de Claude en sus aplicaciones. A diferencia de otras APIs de IA, Claude es particularmente bueno en:

• Seguir las instrucciones con precisión

• Manejar tareas de razonamiento complejas

• Trabajar con herramientas y llamadas a funciones

¿Qué es el MCP (Protocolo de Contexto Modelo)?

Aunque ya hemos hablado qué es un servidor MCPun MCP es una forma estandarizada de conectar asistentes de IA a fuentes de datos y herramientas externas. Piensa en él como un adaptador universal que permite a tu asistente de IA "hablar" con otros servicios como bases de datos, API o aplicaciones.

En lugar de escribir integraciones personalizadas para cada servicio, MCP proporciona una interfaz estándar que los asistentes de IA pueden utilizar para descubrir e interactuar con las herramientas automáticamente.

Cómo trabajan juntos nuestro chatbot, Claude y MCP

Antes de empezar a programar, veamos cómo se conecta todo. Para hablar con Claude, tu chatbot necesita orquestar todas las piezas móviles:

1. Tú (el usuario) escribes un mensaje como: "¿Puedes verificar el saldo de mi Account de Vonage?"

2. El chatbot envía ese mensaje, junto con una lista de herramientas MCP disponibles, a Claude.

3. Claude (la IA) lee tu mensaje y decide si una herramienta puede ayudarte.

   • Si es así, responde con un uso_herramienta especial.

   • Si no, responde directamente.

4. El chatbot detecta esa solicitud de uso de herramienta, ejecuta la herramienta MCP correspondiente (en este caso, "balance") y recoge el resultado.

5. El servidor MCP llama a la API de Vonage entre bastidores para obtener tu saldo.

6. El resultado se devuelve a Claude, que responde naturalmente: "Su saldo actual es de 15,67 USD".

Visual diagram showing how a user request moves through the chatbot, Claude AI, and the Vonage MCP Server to retrieve a real account balance using the Vonage API.

Cómo funciona la lógica de nuestro chatbot

Empecemos por examinar la estructura de nuestro chatbot. Aquí, voy a explicar los componentes básicos y la funcionalidad, pero te darás cuenta de que algunas funciones se omiten. Ir a la sección Cómo ejecutar tu chatbot para implementar el chatbot.

Configurar la clase Chatbot básica

import Anthropic from '@anthropic-ai/sdk';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import readline from 'readline';
import { promisify } from 'util';

class ClaudeChatbot {
  constructor() {
    // Initialize the Anthropic API client
    this.anthropic = new Anthropic({
      apiKey: process.env.ANTHROPIC_API_KEY
    });
    
    // Set up command line interface
    this.rl = readline.createInterface({
      input: process.stdin,
      output: process.stdout
    });
    
    this.question = promisify(this.rl.question).bind(this.rl);
    this.conversationHistory = [];
    
    // MCP-related properties
    this.mcpClients = new Map();
    this.availableTools = new Map();
    this.model = 'claude-3-5-sonnet-20241022';
  }
}

¿Qué está pasando aquí?

Estamos creando una pequeña clase (ClaudeChatbot) para manejar el código del chatbot. Se conecta a la API de Claude, configura algunas herramientas de línea de comandos como readline para leer la entrada del usuario, y luego establece un lugar para almacenar todos los servidores MCP que nuestro código conoce.

Conectarse a servidores MCP

La magia de nuestro chatbot proviene de su capacidad para conectarse a los servidores de MCP. Así es como lo hacemos:

async loadMcpServers() {
  try {
    const configPath = path.join(process.cwd(), 'mcp-config.json');
    const configData = await fs.readFile(configPath, 'utf8');
    const config = JSON.parse(configData);
    
    console.log('📡 Connecting to MCP servers...');
    
    for (const [serverName, serverConfig] of Object.entries(config.mcpServers)) {
      await this.connectMcpServer(serverName, serverConfig);
    }
    
    console.log(`✅ Connected to ${this.mcpClients.size} server(s)`);
  } catch (error) {
    console.log('⚠️  No MCP configuration found, continuing without tools');
  }
}

async connectMcpServer(serverName, config) {
  try {
    // Create a transport layer for communication
    const transport = new StdioClientTransport({
      command: config.command,
      args: config.args,
      env: { ...process.env, ...config.env }
    });

    // Create an MCP client
    const client = new Client({
      name: `claude-chatbot-${serverName}`,
      version: '1.0.0'
    }, {
      capabilities: { tools: {} }
    });

    // Connect and discover available tools
    await client.connect(transport);
    const toolsResponse = await client.listTools();
    
    this.mcpClients.set(serverName, client);
    
    // Register each tool for later use
    for (const tool of toolsResponse.tools) {
      this.availableTools.set(tool.name, {
        serverName,
        tool,
        client
      });
    }
  } catch (error) {
    console.log(`⚠️  Failed to connect to ${serverName}: ${error.message}`);
  }
}

Leeremos un fichero de configuración, mcp-config.jsonque nos dirá qué servidores utilizar y cómo conectarnos a ellos. Para cada servidor, crearemos un objeto StdioClientTransport que se comunicará con cada servidor MCP. Luego nos conectamos al servidor MCP, y llamamos al método listTools() para obtener todas las herramientas disponibles. Todo esto se almacena para que podamos utilizarlos más tarde.

Configuración del servidor MCP de Vonage

Para usar la herramienta de verificación de saldo de Vonage, debemos configurar nuestro servidor MCP. Edita el ejemplo y agrega tu clave y secreto de API de Vonage:

{
  "mcpServers": {
    "vonage": {
      "command": "npx",
      "args": ["-y", "@vonage/vonage-mcp-server-api-bindings"],
      "env": {
        "VONAGE_API_KEY": "abcd",
        "VONAGE_API_SECRET": "1234"
      }
    }
  }
}

Nuestro archivo de configuración le dirá al transporte MCP que ejecute un paquete específico, @vonage/vonage-mcp-server-api-bindingsen la línea de comandos. También especificaremos dos variables de entorno, VONAGE_API_KEY y VONAGE_API_SECRET, que se enviarán a nuestro servidor MCP. La comprobación del saldo de nuestra Account sólo requiere una API Key y un Secret, pero para otras APIs puede ser necesario pasar un Application ID y una clave privada.

Manejar las conversaciones con el servicio de asistencia técnica

Ahora viene la parte emocionante: hacer que Claude conozca nuestras herramientas y dejar que las utilice:

async getClaudeResponse() {
  // Prepare the list of available tools for Claude
  const tools = this.availableTools.size > 0 ? 
    Array.from(this.availableTools.values()).map(toolInfo => ({
      name: toolInfo.tool.name,
      description: toolInfo.tool.description,
      input_schema: toolInfo.tool.inputSchema
    })) : undefined;

  const messageParams = {
    model: this.model,
    max_tokens: 1000,
    messages: this.conversationHistory
  };

  // If we have tools, tell Claude about them
  if (tools && tools.length > 0) {
    messageParams.tools = tools;
  }

  const message = await this.anthropic.messages.create(messageParams);

  // Check if Claude wants to use any tools
  if (message.content.some(content => content.type === 'tool_use')) {
    return await this.handleToolUse(message);
  }

  return message.content[0].text;
}

getClaudeResponse() enviará la lista de servidores MCP, su configuración y el historial de conversaciones a Claude. Los servidores MCP no son invocados directamente por nuestro código, sino que se entregan al LLM backend para que decida si necesita llamar a los servidores MCP. Si Claude decide que necesitamos utilizar una herramienta, devolverá un mensaje del tipo tool_use tipo Si recibimos un mensaje de este tipo, se lo pasaremos al método handleToolUse() para que se encargue de llamar a la herramienta.

Si Claude decide que ninguna herramienta es relevante para el mensaje, simplemente devolvemos el mensaje sin cambios.

Herramientas de ejecución

Cuando Claude decide utilizar una herramienta, ocurre lo siguiente:

async handleToolUse(message) {
  let responseText = '';
  const toolResults = [];

  for (const content of message.content) {
    if (content.type === 'text') {
      responseText += content.text;
    } else if (content.type === 'tool_use') {
      console.log(`🛠️  Using tool: ${content.name}`);
      
      try {
        const toolInfo = this.availableTools.get(content.name);
        
        // Execute the tool through the MCP client
        const result = await toolInfo.client.callTool({
          name: content.name,
          arguments: content.input
        });

        toolResults.push({
          tool_use_id: content.id,
          content: result.content
        });

      } catch (error) {
        console.log(`❌ Tool ${content.name} failed: ${error.message}`);
        toolResults.push({
          tool_use_id: content.id,
          content: `Error: ${error.message}`,
          is_error: true
        });
      }
    }
  }

  // Send the tool results back to Claude for final response
  if (toolResults.length > 0) {
    // Add Claude's tool-use message to history
    this.conversationHistory.push({
      role: 'assistant',
      content: message.content
    });

    // Add tool results to history
    this.conversationHistory.push({
      role: 'user',
      content: toolResults.map(result => ({
        type: 'tool_result',
        tool_use_id: result.tool_use_id,
        content: result.content,
        is_error: result.is_error || false
      }))
    });

    // Get Claude's final response incorporating the tool results
    const followUpMessage = await this.anthropic.messages.create({
      model: this.model,
      max_tokens: 1000,
      messages: this.conversationHistory
    });

    return responseText + followUpMessage.content[0].text;
  }

  return responseText;
}

Si estamos invocando una herramienta, analizaremos el mensaje devuelto por Claude y encontraremos la herramienta que cree que deberíamos llamar. A continuación, iteramos sobre la lista de herramientas que Claude cree que debemos llamar, y a medida que avanzamos recogemos las respuestas de cada herramienta. Todo esto se empaqueta y se envía de vuelta a Claude para proporcionar una respuesta final.

Cómo poner en marcha su chatbot

Clonar el proyecto

En primer lugar, haz una copia del proyecto de inicio y muévete a su interior:

git clone git@github.com:Vonage-Community/blog-mcp-javascript-api_tooling_chatbot.git

cd blog-mcp-javascript-api_tooling_chatbot

Actualizar la configuración de ejemplo

Cambie el nombre de mcp-config.json.ejemplo a mcp-config.json. Y reemplaza los marcadores de posición con tus credenciales de Vonage.

Instalación de dependencias

npm install

Añada sus credenciales antrópicas

Desde la línea de comandos, dé a su proyecto acceso a su clave API de Anthropic:

export ANTHROPIC_API_KEY=your_anthropic_api_key_here

>> Nota: Si estás en un nivel gratuito de Antrhopic, es posible que no tengas acceso a los últimos modelos. Tendrás que actualizar CLAUDE_MODEL en tu archivo chatbot.js en consecuencia.

Ejecutar el chatbot

node chatbot.js 

Ejemplo de conversación

He aquí cómo podría ser una conversación con tu nuevo chatbot:

Animated terminal demo showing a ClaudeChatbot using the Vonage MCP Server to check a user's account balance in real time.

En ese breve intercambio, tu chatbot manejó todo el flujo de trabajo: Claude entendió tu solicitud, invocó la herramienta de saldo a través de MCP y obtuvo datos reales de la API de Vonage.

Por qué esta arquitectura es poderosa

Este enfoque le ofrece varias ventajas:

1. Separación de preocupaciones

• El código de tu chatbot se centra en la gestión de la conversación

• Los servidores MCP gestionan la complejidad de la integración con API externas

• Claude maneja la inteligencia de cuándo y cómo utilizar las herramientas

2. Extensibilidad

• ¿Quieres añadir datos meteorológicos? Sólo tienes que añadir un servidor MCP meteorológico

• ¿Necesitas acceso a bases de datos? Añada un servidor MCP de base de datos

• No es necesario cambiar el código principal del chatbot

3. Normalización

• MCP proporciona una interfaz coherente entre los distintos servicios

• Las herramientas se descubren y documentan automáticamente

• El tratamiento de errores está estandarizado

4. Inteligencia

• Claude decide automáticamente cuándo se necesitan herramientas

• Puede encadenar varias herramientas para realizar tareas complejas

• Ofrece explicaciones en lenguaje natural de lo que está haciendo

Conclusión

¡Enhorabuena! Has construido un chatbot de IA que no sólo puede mantener conversaciones, sino también interactuar con servicios externos a través de herramientas. Este es un poderoso patrón que puedes extender para integrarlo con prácticamente cualquier servicio que tenga un servidor MCP.

La combinación de la API Claude de Anthropic y el Protocolo de Contexto de Modelo crea una plataforma flexible y extensible para crear asistentes de IA que realmente puedan hacer cosas en hacer cosas, no sólo hablar de ellas.

Principales conclusiones:

• La API de Claude proporciona conversaciones inteligentes y toma de decisiones sobre el uso de herramientas

• MCP estandariza el modo en que los asistentes de IA se conectan a servicios externos

• La integración de herramientas se produce automáticamente una vez configuradas las conexiones

• Esta arquitectura es escalable - puede añadir nuevas funciones sin cambiar el código central

Empieza con esta base y experimenta con diferentes servidores MCP para ver qué tipos de asistentes de IA puedes construir. ¡Las posibilidades son infinitas!

Lecturas complementarias

• Documentación de la API antrópica

• Especificación del protocolo de contexto del modelo

• Documentación del servidor MCP de Vonage

• Servidores MCP disponibles