Eventos MCP en conversaciones de voz
En esta página
MCP en el Agente de Voz
El Protocolo de Contexto de Modelo (MCP) permite que tu agente de voz se conecte a servidores de herramientas externos mediante un protocolo estandarizado. Cuando configuras una herramienta MCP en tu sesión, la API del Agente de Voz emite eventos específicos para cada paso de la interacción con el servidor MCP.
Configurar una herramienta MCP
Para habilitar un servidor MCP en tu sesión de voz, añádelo a la lista de herramientas:
{
"type": "session.update",
"session": {
"tools": [
{
"type": "mcp",
"server_url": "https://mon-serveur-mcp.exemple.com/sse",
"server_label": "Internal CRM"
}
]
}
}
El campo server_url apunta a tu servidor MCP y server_label es un nombre legible que identifica al servidor en los registros.
Descubrimiento de herramientas
Cuando el agente se conecta al servidor MCP, primero recupera la lista de herramientas disponibles. Tres eventos marcan esta fase.
mcp_list_tools.in_progress
{
"type": "mcp_list_tools.in_progress",
"server_label": "Internal CRM"
}
Se está consultando al servidor MCP para obtener su lista de herramientas.
mcp_list_tools.completed
{
"type": "mcp_list_tools.completed",
"server_label": "Internal CRM",
"tools": [
{
"name": "find_customer",
"description": "Finds a customer by name or email"
},
{
"name": "create_ticket",
"description": "Creates a support ticket"
}
]
}
La lista de herramientas se ha recuperado correctamente. El agente de voz ya puede utilizarlas en la conversación.
mcp_list_tools.failed
{
"type": "mcp_list_tools.failed",
"server_label": "Internal CRM",
"error": {
"message": "Connection timeout"
}
}
La conexión con el servidor MCP ha fallado. El agente continuará la conversación sin esas herramientas.
Llamadas a herramientas MCP
Cuando el agente decide utilizar una herramienta MCP durante la conversación, se emiten más eventos.
response.mcp_call_arguments.delta / .done
Al igual que los eventos habituales de llamada a funciones, estos transmiten los argumentos de la llamada:
{
"type": "response.mcp_call_arguments.delta",
"delta": "{\"name\": \"Mil"
}
{
"type": "response.mcp_call_arguments.done",
"arguments": "{\"name\": \"Miller\"}"
}
response.mcp_call.in_progress / .completed / .failed
Estos eventos rastrean la ejecución de la llamada en el servidor MCP:
{
"type": "response.mcp_call.in_progress",
"server_label": "Internal CRM",
"tool_name": "find_customer"
}
{
"type": "response.mcp_call.completed",
"server_label": "Internal CRM",
"tool_name": "find_customer",
"result": "{\"id\": 42, \"name\": \"Miller\", \"email\": \"[email protected]\"}"
}
{
"type": "response.mcp_call.failed",
"server_label": "Internal CRM",
"tool_name": "find_customer",
"error": {
"message": "Customer not found"
}
}
Diferencias con la llamada a funciones habitual
Las herramientas MCP se ejecutan en el lado del servidor, a través de la infraestructura de xAI, por lo que no tienes que gestionar la ejecución tú mismo. Esta es la principal diferencia respecto a la llamada a funciones habitual, donde tu aplicación debe ejecutar la función y devolver el resultado.
| Aspecto | Llamada a funciones | MCP |
|---|---|---|
| Ejecución | Tu aplicación | Servidor MCP remoto |
| Resultado | Lo envías tú | Automático |
| Latencia | Depende de tu código | Depende del servidor MCP |
| Configuración | Esquema JSON local | URL del servidor MCP |
Gestionar eventos MCP en tu aplicación
Aquí tienes un ejemplo de un gestor completo para eventos MCP:
ws.on("message", (data) => {
const event = JSON.parse(data);
switch (event.type) {
case "mcp_list_tools.in_progress":
console.log(`Conectando al servidor MCP: ${event.server_label}`);
break;
case "mcp_list_tools.completed":
console.log(`Herramientas disponibles: ${event.tools.length}`);
break;
case "mcp_list_tools.failed":
console.error(`Error 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(`Herramienta ${event.tool_name} no disponible`);
break;
}
});
Puntos clave
- Las herramientas MCP permiten que el agente de voz trabaje con servidores externos mediante un protocolo estandarizado
- El descubrimiento de herramientas ocurre automáticamente a través de los eventos
mcp_list_tools - Las llamadas MCP se ejecutan en el lado del servidor, a diferencia de la llamada a funciones habitual
- Cada llamada pasa por tres estados posibles:
in_progress, seguido decompletedofailed - Gestiona los fallos de conexión MCP con elegancia: el agente puede continuar sin las herramientas