Événements MCP en conversation vocale

MCP dans le Voice Agent

Le Model Context Protocol (MCP) permet à votre agent vocal de se connecter à des serveurs d’outils externes via un protocole standardisé. Quand vous configurez un outil MCP dans votre session, l’API Voice Agent émet des événements spécifiques pour chaque étape de l’interaction avec le serveur MCP.

Configuration d’un outil MCP

Pour activer un serveur MCP dans votre session vocale, ajoutez-le dans la liste des outils :

{
  "type": "session.update",
  "session": {
    "tools": [
      {
        "type": "mcp",
        "server_url": "https://mon-serveur-mcp.exemple.com/sse",
        "server_label": "CRM interne"
      }
    ]
  }
}

Le champ server_url pointe vers votre serveur MCP, et server_label est un nom lisible pour identifier le serveur dans les logs.

Découverte des outils MCP

Lorsque l’agent se connecte au serveur MCP, il récupère d’abord la liste des outils disponibles. Trois événements marquent cette phase :

mcp_list_tools.in_progress

{
  "type": "mcp_list_tools.in_progress",
  "server_label": "CRM interne"
}

Le serveur MCP est en cours de consultation pour récupérer la liste de ses outils.

mcp_list_tools.completed

{
  "type": "mcp_list_tools.completed",
  "server_label": "CRM interne",
  "tools": [
    {
      "name": "rechercher_client",
      "description": "Recherche un client par nom ou email"
    },
    {
      "name": "creer_ticket",
      "description": "Crée un ticket de support"
    }
  ]
}

La liste des outils a été récupérée avec succès. L’agent vocal peut maintenant les utiliser dans la conversation.

mcp_list_tools.failed

{
  "type": "mcp_list_tools.failed",
  "server_label": "CRM interne",
  "error": {
    "message": "Connection timeout"
  }
}

La connexion au serveur MCP a échoué. L’agent continuera la conversation sans ces outils.

Appels d’outils MCP

Quand l’agent décide d’utiliser un outil MCP pendant la conversation, trois événements supplémentaires sont émis :

response.mcp_call_arguments.delta / .done

Similaires aux événements de function calling classique, ces événements transmettent les arguments de l’appel en streaming :

{
  "type": "response.mcp_call_arguments.delta",
  "delta": "{\"nom\": \"Dup"
}

{
  "type": "response.mcp_call_arguments.done",
  "arguments": "{\"nom\": \"Dupont\"}"
}

response.mcp_call.in_progress / .completed / .failed

Ces événements suivent l’exécution de l’appel sur le serveur MCP :

{
  "type": "response.mcp_call.in_progress",
  "server_label": "CRM interne",
  "tool_name": "rechercher_client"
}

{
  "type": "response.mcp_call.completed",
  "server_label": "CRM interne",
  "tool_name": "rechercher_client",
  "result": "{\"id\": 42, \"nom\": \"Dupont\", \"email\": \"[email protected]\"}"
}

{
  "type": "response.mcp_call.failed",
  "server_label": "CRM interne",
  "tool_name": "rechercher_client",
  "error": {
    "message": "Client non trouvé"
  }
}

Différence avec le function calling classique

Les outils MCP sont exécutés côté serveur par l’infrastructure xAI. Vous n’avez pas à gérer l’exécution vous-même. C’est la principale différence avec le function calling classique où votre application doit exécuter la fonction et renvoyer le résultat.

Gestion des événements MCP dans votre application

Voici un exemple de handler complet pour les événements MCP :

ws.on("message", (data) => {
  const event = JSON.parse(data);

  switch (event.type) {
    case "mcp_list_tools.in_progress":
      console.log(`Connexion au serveur MCP : ${event.server_label}`);
      break;

    case "mcp_list_tools.completed":
      console.log(`Outils disponibles : ${event.tools.length}`);
      break;

    case "mcp_list_tools.failed":
      console.error(`Erreur MCP : ${event.error.message}`);
      break;

    case "response.mcp_call.in_progress":
      showToolIndicator(event.tool_name);
      break;

    case "response.mcp_call.completed":
      hideToolIndicator();
      break;

    case "response.mcp_call.failed":
      hideToolIndicator();
      showError(`Outil ${event.tool_name} indisponible`);
      break;
  }
});

Points clés à retenir

• Les outils MCP permettent à l’agent vocal d’interagir avec des serveurs externes via un protocole standardisé
• La découverte des outils se fait automatiquement via les événements mcp_list_tools
• Les appels MCP sont exécutés côté serveur, contrairement au function calling classique
• Trois phases pour chaque appel : in_progress, completed ou failed
• Gérez les échecs de connexion MCP gracieusement : l’agent peut continuer sans les outils