MCP Client

Connect voice agents to Model Context Protocol servers

MCP Client

Connect voice agents to Model Context Protocol servers

For the complete documentation index, see llms.txt.

The VoxEngine MCP Client lets a VoxEngine scenario connect to Model Context Protocol servers and call their tools from a live voice workflow.

Use it when your voice agent needs access to tools exposed through an MCP server, such as CRM lookups, scheduling systems, internal databases, or automation platforms. VoxEngine keeps the realtime call and voice orchestration inside your scenario while the MCP server provides the external tool layer.

How it works

To call MCP tools from a VoxEngine scenario:

Require the Modules.MCP module.
Create an MCP.Client with MCP.createClient(...).
Pass an mcpServerConnectionConfig object with the MCP server endpoint and transport.
Listen for MCP.ServerEvents.ConnectorInformation, then call mcpClient.listTools({}).
Call a tool with mcpClient.callTool(...).
Handle MCP.ServerEvents.ToolResult and MCP.ServerEvents.MCPError in your business logic.

See the MCP API Reference for the full list of client parameters, methods, and events.

Prerequisites

A Voximplant application with an inbound route that points to your scenario.
A reachable MCP server endpoint that supports http or sse transport.
Any required MCP server credentials stored in Voximplant Secrets.

Connection configuration

MCP.createClient(...) accepts mcpServerConnectionConfig, which describes the MCP server connection:

MCP connection config

1 const mcpClient = await MCP.createClient({
2     mcpServerConnectionConfig: {
3         transport: "sse",
4         endpoint: VoxEngine.getSecretValue("MCP_SERVER_URL"),
5         headers: {
6             Authorization: `Bearer ${VoxEngine.getSecretValue("MCP_SERVER_TOKEN")}`,
7         },
8         clientName: "voximplant-voice-agent",
9         clientVersion: "1.0.0",
10     },
11     onWebSocketClose: (event) => {
12         Logger.write("===MCP_CONNECTION_CLOSED===");
13         if (event) Logger.write(JSON.stringify(event));
14         VoxEngine.terminate();
15     },
16 });

Transport options

The MCP client supports http and sse transports. Use the transport expected by your MCP server.

Full VoxEngine scenario

This example answers an inbound call, connects to an MCP server, lists available tools, calls a demo roll tool, and logs the result. It expects MCP_SERVER_URL and MCP_SERVER_TOKEN secrets.

mcp-client-example.js

1 require(Modules.MCP);
2 
3 const MCP_TOOL_NAME = "roll";
4 
5 VoxEngine.addEventListener(AppEvents.CallAlerting, async ({call}) => {
6     let mcpClient;
7 
8     const cleanup = () => {
9         if (mcpClient) mcpClient.close();
10         VoxEngine.terminate();
11     };
12 
13     call.addEventListener(CallEvents.Disconnected, cleanup);
14     call.addEventListener(CallEvents.Failed, cleanup);
15 
16     try {
17         call.answer();
18 
19         mcpClient = await MCP.createClient({
20             mcpServerConnectionConfig: {
21                 transport: "sse",
22                 endpoint: VoxEngine.getSecretValue("MCP_SERVER_URL"),
23                 headers: {
24                     Authorization: `Bearer ${VoxEngine.getSecretValue("MCP_SERVER_TOKEN")}`,
25                 },
26                 clientName: "voximplant-mcp-demo",
27                 clientVersion: "1.0.0",
28             },
29             onWebSocketClose: (event) => {
30                 Logger.write("===MCP_CONNECTION_CLOSED===");
31                 if (event) Logger.write(JSON.stringify(event));
32                 VoxEngine.terminate();
33             },
34         });
35 
36         mcpClient.addEventListener(MCP.ServerEvents.MCPError, (event) => {
37             Logger.write("===MCP_ERROR===");
38             Logger.write(JSON.stringify(event.data));
39         });
40 
41         mcpClient.addEventListener(MCP.ServerEvents.ConnectorInformation, () => {
42             Logger.write("===MCP_CONNECTED===");
43             mcpClient.listTools({});
44         });
45 
46         mcpClient.addEventListener(MCP.ServerEvents.ToolsList, (event) => {
47             const tools = event.data.payload.tools;
48 
49             Logger.write("===MCP_TOOLS_LIST===");
50             Logger.write(JSON.stringify(tools.map((tool) => tool.name)));
51 
52             mcpClient.callTool({
53                 name: MCP_TOOL_NAME,
54                 arguments: {
55                     diceRollExpression: "2d6 + 1d4",
56                 },
57             });
58         });
59 
60         mcpClient.addEventListener(MCP.ServerEvents.ToolResult, (event) => {
61             Logger.write("===MCP_TOOL_RESULT===");
62             Logger.write(JSON.stringify(event.data));
63             cleanup();
64         });
65     } catch (error) {
66         Logger.write("===MCP_CLIENT_ERROR===");
67         Logger.write(error);
68         if (mcpClient) mcpClient.close();
69         VoxEngine.terminate();
70     }
71 });

How it works

To call MCP tools from a VoxEngine scenario:

Require the Modules.MCP module.
Create an MCP.Client with MCP.createClient(...).
Pass an mcpServerConnectionConfig object with the MCP server endpoint and transport.
Listen for MCP.ServerEvents.ConnectorInformation, then call mcpClient.listTools({}).
Call a tool with mcpClient.callTool(...).
Handle MCP.ServerEvents.ToolResult and MCP.ServerEvents.MCPError in your business logic.

See the MCP API Reference for the full list of client parameters, methods, and events.

Prerequisites

A Voximplant application with an inbound route that points to your scenario.
A reachable MCP server endpoint that supports http or sse transport.
Any required MCP server credentials stored in Voximplant Secrets.

Connection configuration

MCP.createClient(...) accepts mcpServerConnectionConfig, which describes the MCP server connection:

MCP connection config

1 const mcpClient = await MCP.createClient({
2     mcpServerConnectionConfig: {
3         transport: "sse",
4         endpoint: VoxEngine.getSecretValue("MCP_SERVER_URL"),
5         headers: {
6             Authorization: `Bearer ${VoxEngine.getSecretValue("MCP_SERVER_TOKEN")}`,
7         },
8         clientName: "voximplant-voice-agent",
9         clientVersion: "1.0.0",
10     },
11     onWebSocketClose: (event) => {
12         Logger.write("===MCP_CONNECTION_CLOSED===");
13         if (event) Logger.write(JSON.stringify(event));
14         VoxEngine.terminate();
15     },
16 });

Transport options

The MCP client supports http and sse transports. Use the transport expected by your MCP server.

Full VoxEngine scenario

This example answers an inbound call, connects to an MCP server, lists available tools, calls a demo roll tool, and logs the result. It expects MCP_SERVER_URL and MCP_SERVER_TOKEN secrets.

mcp-client-example.js

1 require(Modules.MCP);
2 
3 const MCP_TOOL_NAME = "roll";
4 
5 VoxEngine.addEventListener(AppEvents.CallAlerting, async ({call}) => {
6     let mcpClient;
7 
8     const cleanup = () => {
9         if (mcpClient) mcpClient.close();
10         VoxEngine.terminate();
11     };
12 
13     call.addEventListener(CallEvents.Disconnected, cleanup);
14     call.addEventListener(CallEvents.Failed, cleanup);
15 
16     try {
17         call.answer();
18 
19         mcpClient = await MCP.createClient({
20             mcpServerConnectionConfig: {
21                 transport: "sse",
22                 endpoint: VoxEngine.getSecretValue("MCP_SERVER_URL"),
23                 headers: {
24                     Authorization: `Bearer ${VoxEngine.getSecretValue("MCP_SERVER_TOKEN")}`,
25                 },
26                 clientName: "voximplant-mcp-demo",
27                 clientVersion: "1.0.0",
28             },
29             onWebSocketClose: (event) => {
30                 Logger.write("===MCP_CONNECTION_CLOSED===");
31                 if (event) Logger.write(JSON.stringify(event));
32                 VoxEngine.terminate();
33             },
34         });
35 
36         mcpClient.addEventListener(MCP.ServerEvents.MCPError, (event) => {
37             Logger.write("===MCP_ERROR===");
38             Logger.write(JSON.stringify(event.data));
39         });
40 
41         mcpClient.addEventListener(MCP.ServerEvents.ConnectorInformation, () => {
42             Logger.write("===MCP_CONNECTED===");
43             mcpClient.listTools({});
44         });
45 
46         mcpClient.addEventListener(MCP.ServerEvents.ToolsList, (event) => {
47             const tools = event.data.payload.tools;
48 
49             Logger.write("===MCP_TOOLS_LIST===");
50             Logger.write(JSON.stringify(tools.map((tool) => tool.name)));
51 
52             mcpClient.callTool({
53                 name: MCP_TOOL_NAME,
54                 arguments: {
55                     diceRollExpression: "2d6 + 1d4",
56                 },
57             });
58         });
59 
60         mcpClient.addEventListener(MCP.ServerEvents.ToolResult, (event) => {
61             Logger.write("===MCP_TOOL_RESULT===");
62             Logger.write(JSON.stringify(event.data));
63             cleanup();
64         });
65     } catch (error) {
66         Logger.write("===MCP_CLIENT_ERROR===");
67         Logger.write(error);
68         if (mcpClient) mcpClient.close();
69         VoxEngine.terminate();
70     }
71 });

MCP Client

MCP Client

How it works

Prerequisites

Connection configuration

Transport options

Full VoxEngine scenario

See also

How it works

Prerequisites

Connection configuration

Transport options

Full VoxEngine scenario

See also

1	const mcpClient = await MCP.createClient({
2	mcpServerConnectionConfig: {
3	transport: "sse",
4	endpoint: VoxEngine.getSecretValue("MCP_SERVER_URL"),
5	headers: {
6	Authorization: `Bearer ${VoxEngine.getSecretValue("MCP_SERVER_TOKEN")}`,
7	},
8	clientName: "voximplant-voice-agent",
9	clientVersion: "1.0.0",
10	},
11	onWebSocketClose: (event) => {
12	Logger.write("===MCP_CONNECTION_CLOSED===");
13	if (event) Logger.write(JSON.stringify(event));
14	VoxEngine.terminate();
15	},
16	});

1	require(Modules.MCP);
2
3	const MCP_TOOL_NAME = "roll";
4
5	VoxEngine.addEventListener(AppEvents.CallAlerting, async ({call}) => {
6	let mcpClient;
7
8	const cleanup = () => {
9	if (mcpClient) mcpClient.close();
10	VoxEngine.terminate();
11	};
12
13	call.addEventListener(CallEvents.Disconnected, cleanup);
14	call.addEventListener(CallEvents.Failed, cleanup);
15
16	try {
17	call.answer();
18
19	mcpClient = await MCP.createClient({
20	mcpServerConnectionConfig: {
21	transport: "sse",
22	endpoint: VoxEngine.getSecretValue("MCP_SERVER_URL"),
23	headers: {
24	Authorization: `Bearer ${VoxEngine.getSecretValue("MCP_SERVER_TOKEN")}`,
25	},
26	clientName: "voximplant-mcp-demo",
27	clientVersion: "1.0.0",
28	},
29	onWebSocketClose: (event) => {
30	Logger.write("===MCP_CONNECTION_CLOSED===");
31	if (event) Logger.write(JSON.stringify(event));
32	VoxEngine.terminate();
33	},
34	});
35
36	mcpClient.addEventListener(MCP.ServerEvents.MCPError, (event) => {
37	Logger.write("===MCP_ERROR===");
38	Logger.write(JSON.stringify(event.data));
39	});
40
41	mcpClient.addEventListener(MCP.ServerEvents.ConnectorInformation, () => {
42	Logger.write("===MCP_CONNECTED===");
43	mcpClient.listTools({});
44	});
45
46	mcpClient.addEventListener(MCP.ServerEvents.ToolsList, (event) => {
47	const tools = event.data.payload.tools;
48
49	Logger.write("===MCP_TOOLS_LIST===");
50	Logger.write(JSON.stringify(tools.map((tool) => tool.name)));
51
52	mcpClient.callTool({
53	name: MCP_TOOL_NAME,
54	arguments: {
55	diceRollExpression: "2d6 + 1d4",
56	},
57	});
58	});
59
60	mcpClient.addEventListener(MCP.ServerEvents.ToolResult, (event) => {
61	Logger.write("===MCP_TOOL_RESULT===");
62	Logger.write(JSON.stringify(event.data));
63	cleanup();
64	});
65	} catch (error) {
66	Logger.write("===MCP_CLIENT_ERROR===");
67	Logger.write(error);
68	if (mcpClient) mcpClient.close();
69	VoxEngine.terminate();
70	}
71	});