Passo a passo: como adicionar APIs da Vonage ao seu agente de IA com o MCP

Introdução

Você já pensou em criar seu próprio chatbot de IA que fosse capaz de fazer mais do que apenas responder perguntas? E se o seu chatbot pudesse verificar o saldo da sua Account, enviar mensagens em seu nome ou interagir com outros serviços? É exatamente isso que vamos aprender a criar hoje usando a API Claude da Anthropic e o novo Servidor de Ligações da API do Vonage Model Context Protocol (MCP) (também conhecido como: Servidor de Ferramentas).

Neste tutorial, vamos criar um chatbot capaz de conversar com você e, ao mesmo tempo, utilizar ferramentas externas — mais especificamente, faremos a integração com o Vonage Tooling MCP Server para verificar saldos de contas, a título de exemplo.

Resumo: Você pode encontrar o exemplo completo em funcionamento em nosso repositório do GitHub.

Pré-requisitos

Antes de começarmos, certifique-se de que você tenha:

• Node.js instalado (versão 14 ou superior)

• Conhecimentos básicos de JavaScript

• Uma chave de API da Anthropic 

• Um account da API da Vonage (para o exemplo de consulta de saldo)

Compreendendo os conceitos fundamentais

O que é a API Claude da Anthropic?

Claude é o assistente de IA da Anthropic que se destaca na compreensão e geração de linguagem natural. A API permite que você integre os recursos do Claude às suas Applications. Ao contrário de algumas outras APIs de IA, o Claude é particularmente bom em:

• Seguir as instruções à risca

• Lidando com tarefas complexas de raciocínio

• Trabalhando com ferramentas e chamadas de função

O que é o MCP (Protocolo de Contexto de Modelo)?

Embora já tenhamos falado sobre o que é um servidor MCP, um MCP é uma forma padronizada de conectar assistentes de IA a fontes de dados e ferramentas externas. Pense nisso como um adaptador universal que permite que seu assistente de IA “converse” com outros serviços, como bancos de dados, APIs ou Applications.

Em vez de criar integrações personalizadas para cada serviço, o MCP oferece uma interface padrão que os assistentes de IA podem usar para identificar e interagir com as ferramentas automaticamente.

Como nosso chatbot, Claude, e o MCP funcionam juntos

Antes de começarmos a programar, vamos visualizar como tudo se conecta. Para se comunicar com o Claude, seu chatbot precisa coordenar todos os elementos envolvidos: 

1. Você (o usuário) digita uma mensagem como: “Você pode verificar o saldo da minha conta da Vonage?”

2. O chatbot envia essa mensagem, juntamente com uma lista das ferramentas MCP disponíveis, para o Claude.

3. Claude (a IA) lê sua mensagem e decide se alguma ferramenta pode ajudar.

   • Nesse caso, ele responde com uma tool_use .

   • Caso contrário, ele simplesmente responde diretamente.

4. O chatbot detecta essa solicitação de uso de ferramenta, executa a ferramenta MCP correspondente (neste caso, “balance”) e coleta o resultado.

5. O servidor MCP acessa a API da Vonage em segundo plano para obter seu saldo.

6. O resultado é enviado ao Claude, que então responde de forma natural: “Seu saldo atual é de US$ 15,67.”

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.

Como funciona a lógica do nosso chatbot

Vamos começar examinando a estrutura do nosso chatbot. Aqui, explicarei os principais componentes e funcionalidades, mas você vai perceber que algumas funções foram omitidas. Pule para a seção “Como executar seu chatbot” para implementar o chatbot.

Configurar a classe básica do chatbot

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';
  }
}

O que está acontecendo aqui?

Estamos criando uma pequena classe (ClaudeChatbot) para lidar com o código do chatbot. Ela se conecta à API do Claude, configura algumas ferramentas de linha de comando, como readline para ler as entradas do usuário e, em seguida, define um local para armazenar todos os servidores MCP que nosso código reconhece.

Conectar-se aos servidores MCP

A magia do nosso chatbot vem de sua capacidade de se conectar aos servidores do MCP. Veja como fazemos isso:

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}`);
  }
}

Vamos ler um arquivo de configuração, mcp-config.jsonque nos indicará quais servidores usar e como nos conectar a eles. Para cada servidor, criamos um StdioClientTransport objeto, que se comunicará com cada servidor MCP. Em seguida, nos conectamos ao servidor MCP e chamamos o listTools() método para obter todas as ferramentas disponíveis. Tudo isso é armazenado para que possamos usá-las posteriormente.

Configuração do servidor MCP da Vonage

Para usar a ferramenta de verificação de saldo da Vonage, precisamos configurar nosso servidor MCP. Edite o exemplo e adicione sua chave e seu segredo da API da Vonage:

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

Nosso arquivo de configuração instruirá o transporte MCP a executar um pacote específico, @vonage/vonage-mcp-server-api-bindings, na linha de comando. Também especificaremos duas variáveis de ambiente, VONAGE_API_KEY e VONAGE_API_SECRET, que serão enviadas ao nosso servidor MCP. Para verificar o saldo da nossa conta, basta uma chave API e um segredo API, mas, para outras APIs, talvez seja necessário passar um ID de aplicativo e uma chave privada.

Como lidar com conversas com o suporte técnico

Agora vem a parte emocionante: apresentar nossas ferramentas ao Claude e permitir que ele as utilize:

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á a lista de servidores MCP, sua configuração e o histórico de conversas para o Claude. Os servidores MCP não são chamados diretamente pelo nosso código, mas sim repassados ao LLM de back-end para que ele decida se é necessário acioná-los. Se o Claude decidir que precisamos usar uma ferramenta, ele retornará uma mensagem do tool_use tipo. Se recebermos essa mensagem, a repassaremos ao handleToolUse() método para que ele cuide da chamada da ferramenta.

Se Claude decidir que nenhuma ferramenta é relevante para a mensagem, simplesmente retornamos a mensagem sem alterações.

Ferramentas de execução

Quando Claude decide usar uma ferramenta, é isso que acontece:

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;
}

Se estivermos invocando uma ferramenta, analisaremos a mensagem retornada pelo Claude e identificaremos a ferramenta que ele considera que devemos chamar. Em seguida, percorremos a lista de ferramentas que o Claude acredita que devemos chamar e, à medida que avançamos, coletamos as respostas de cada uma delas. Tudo isso é agrupado e enviado de volta ao Claude para fornecer uma resposta final.

Como operar seu chatbot

Clonar o projeto

Primeiro, faça uma cópia do projeto inicial e entre nela:

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

cd blog-mcp-javascript-api_tooling_chatbot

Atualizar a configuração de exemplo

Altere o nome do arquivo mcp-config.json.example para mcp-config.json. E substitua os espaços reservados pelas suas credenciais da Vonage.

Instalando dependências

npm install

Adicione suas credenciais da Anthropic

Na linha de comando, conceda ao seu projeto acesso à sua chave de API da Anthropic:

export ANTHROPIC_API_KEY=your_anthropic_api_key_here

>> Observação: Se você estiver em um plano gratuito da Anthropic, talvez não tenha acesso aos modelos mais recentes. Você precisará atualizar CLAUDE_MODEL no seu chatbot.js conforme necessário.

Execute o chatbot

node chatbot.js 

Exemplo de conversa

Veja como poderia ser uma conversa com seu novo chatbot:

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

Nessa breve troca de mensagens, seu chatbot cuidou de todo o fluxo de trabalho: o Claude entendeu sua solicitação, acionou a ferramenta de saldo por meio do MCP e obteve dados reais da API da Vonage.

Por que essa arquitetura é poderosa

Essa abordagem oferece várias vantagens:

1. Separação de interesses

• O código do seu chatbot se concentra no gerenciamento de conversas

• Os servidores MCP lidam com a complexidade da integração com APIs externas

• Claude sabe quando e como usar as ferramentas

2. Extensibilidade

• Quer adicionar dados meteorológicos? Basta adicionar um servidor MCP de meteorologia

• Precisa de acesso a um banco de dados? Adicione um servidor MCP de banco de dados

• O código principal do chatbot não precisa ser alterado

3. Padronização

• O MCP oferece uma interface consistente entre os diferentes serviços

• As ferramentas são detectadas e documentadas automaticamente

• O tratamento de erros é padronizado

4. Inteligência

• O Claude decide automaticamente quando as ferramentas são necessárias

• Ele pode encadear várias ferramentas para realizar tarefas complexas

• Ele fornece explicações em linguagem natural sobre o que está fazendo

Conclusão

Parabéns! Você criou um chatbot de IA que não só consegue manter conversas, mas também interagir com serviços externos por meio de ferramentas. Esse é um padrão poderoso que você pode ampliar para integrar-se a praticamente qualquer serviço que possua um servidor MCP.

A combinação da API Claude, da Anthropic, com o Protocolo de Contexto do Modelo cria uma plataforma flexível e extensível para a criação de assistentes de IA que realmente possam fazer coisas, e não apenas falar sobre elas.

Pontos principais:

• A API do Claude oferece conversas inteligentes e tomada de decisões sobre o uso de ferramentas

• MCP padroniza a forma como os assistentes de IA se conectam a serviços externos

• Integração de ferramentas ocorre automaticamente assim que você configurar as conexões

• Essa arquitetura é escalável — é possível adicionar novos recursos sem alterar o código principal

Comece com essa base e experimente diferentes servidores MCP para ver que tipos de assistentes de IA você pode criar. As possibilidades são infinitas!

Leitura complementar

• Documentação da API da Anthropic

• Especificação do Protocolo de Contexto do Modelo

• Documentação do servidor MCP da Vonage

• Servidores MCP disponíveis