> For a complete documentation index, fetch https://docs.voximplant.ai/llms.txt

# MCP Client

<blockquote>
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

The VoxEngine MCP Client lets a VoxEngine scenario connect to [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) 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:

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

See the [MCP API Reference](/api-reference/voxengine/mcp) for the full list of client parameters, methods, and events.

## Prerequisites

* A Voximplant [application](/platform/voxengine/applications) with an inbound route that points to your [scenario](/platform/voxengine/scenarios).
* A reachable MCP server endpoint that supports `http` or `sse` transport.
* Any required MCP server credentials stored in [Voximplant Secrets](/platform/voxengine/secrets).

## Connection configuration

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

```js title="MCP connection config"
const mcpClient = await MCP.createClient({
    mcpServerConnectionConfig: {
        transport: "sse",
        endpoint: VoxEngine.getSecretValue("MCP_SERVER_URL"),
        headers: {
            Authorization: `Bearer ${VoxEngine.getSecretValue("MCP_SERVER_TOKEN")}`,
        },
        clientName: "voximplant-voice-agent",
        clientVersion: "1.0.0",
    },
    onWebSocketClose: (event) => {
        Logger.write("===MCP_CONNECTION_CLOSED===");
        if (event) Logger.write(JSON.stringify(event));
        VoxEngine.terminate();
    },
});
```

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.

```javascript title="mcp-client-example.js"
require(Modules.MCP);

const MCP_TOOL_NAME = "roll";

VoxEngine.addEventListener(AppEvents.CallAlerting, async ({call}) => {
    let mcpClient;

    const cleanup = () => {
        if (mcpClient) mcpClient.close();
        VoxEngine.terminate();
    };

    call.addEventListener(CallEvents.Disconnected, cleanup);
    call.addEventListener(CallEvents.Failed, cleanup);

    try {
        call.answer();

        mcpClient = await MCP.createClient({
            mcpServerConnectionConfig: {
                transport: "sse",
                endpoint: VoxEngine.getSecretValue("MCP_SERVER_URL"),
                headers: {
                    Authorization: `Bearer ${VoxEngine.getSecretValue("MCP_SERVER_TOKEN")}`,
                },
                clientName: "voximplant-mcp-demo",
                clientVersion: "1.0.0",
            },
            onWebSocketClose: (event) => {
                Logger.write("===MCP_CONNECTION_CLOSED===");
                if (event) Logger.write(JSON.stringify(event));
                VoxEngine.terminate();
            },
        });

        mcpClient.addEventListener(MCP.ServerEvents.MCPError, (event) => {
            Logger.write("===MCP_ERROR===");
            Logger.write(JSON.stringify(event.data));
        });

        mcpClient.addEventListener(MCP.ServerEvents.ConnectorInformation, () => {
            Logger.write("===MCP_CONNECTED===");
            mcpClient.listTools({});
        });

        mcpClient.addEventListener(MCP.ServerEvents.ToolsList, (event) => {
            const tools = event.data.payload.tools;

            Logger.write("===MCP_TOOLS_LIST===");
            Logger.write(JSON.stringify(tools.map((tool) => tool.name)));

            mcpClient.callTool({
                name: MCP_TOOL_NAME,
                arguments: {
                    diceRollExpression: "2d6 + 1d4",
                },
            });
        });

        mcpClient.addEventListener(MCP.ServerEvents.ToolResult, (event) => {
            Logger.write("===MCP_TOOL_RESULT===");
            Logger.write(JSON.stringify(event.data));
            cleanup();
        });
    } catch (error) {
        Logger.write("===MCP_CLIENT_ERROR===");
        Logger.write(error);
        if (mcpClient) mcpClient.close();
        VoxEngine.terminate();
    }
});
```

## See also

* [MCP API Reference](/api-reference/voxengine/mcp)
* [MCP Client methods](/api-reference/voxengine/mcp/client)
* [MCP server events](/api-reference/voxengine/mcp/server-events)
* [Secret storage](/platform/voxengine/secrets)