MCP events in voice conversations

MCP in the Voice Agent

The Model Context Protocol (MCP) lets your voice agent connect to external tool servers through a standardized protocol. When you configure an MCP tool in your session, the Voice Agent API emits specific events for each step of the interaction with the MCP server.

Configure an MCP tool

To enable an MCP server in your voice session, add it to the list of tools:

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

The server_url field points to your MCP server, and server_label is a readable name that identifies the server in the logs.

Tool discovery

When the agent connects to the MCP server, it first fetches the list of available tools. Three events mark this phase.

mcp_list_tools.in_progress

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

The MCP server is being queried for its list of tools.

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"
    }
  ]
}

The list of tools was fetched successfully. The voice agent can now use them in the conversation.

mcp_list_tools.failed

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

The connection to the MCP server failed. The agent will carry on with the conversation without those tools.

MCP tool calls

When the agent decides to use an MCP tool during the conversation, more events are emitted.

response.mcp_call_arguments.delta / .done

Like the regular function calling events, these stream the call’s arguments:

{
  "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

These events track the execution of the call on the MCP server:

{
  "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"
  }
}

How it differs from regular function calling

MCP tools run on the server side, through xAI’s infrastructure, so you don’t have to handle execution yourself. That’s the main difference from regular function calling, where your app must run the function and send back the result.

Handle MCP events in your app

Here’s an example of a complete handler for MCP events:

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

  switch (event.type) {
    case "mcp_list_tools.in_progress":
      console.log(`Connecting to MCP server: ${event.server_label}`);
      break;

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

    case "mcp_list_tools.failed":
      console.error(`MCP error: ${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(`Tool ${event.tool_name} unavailable`);
      break;
  }
});

Key takeaways

• MCP tools let the voice agent work with external servers through a standardized protocol
• Tool discovery happens automatically through the mcp_list_tools events
• MCP calls run on the server side, unlike regular function calling
• Each call goes through three possible states: in_progress, then completed or failed
• Handle MCP connection failures gracefully: the agent can carry on without the tools