MCP Integration

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI agents connect to external tools and data sources through a standardized server interface. Instead of writing a custom webhook for every integration, you deploy an MCP server that exposes a set of named tools — and any AI that speaks MCP can discover and call them automatically.

Common MCP use cases include querying internal databases, looking up CRM records, checking inventory, reading calendars, or calling any REST API your business already has. Because the protocol is standardized, the same MCP server can be reused across different AI applications without modification.

How VNS Uses MCP

When VNS receives your CallStart response it splits it in two: the VoiceElements_Instructions block is consumed by VNS itself, and the session.update portion — including any MCP server definitions in the tools array — is forwarded to the AI model. The AI handles connecting to MCP servers directly. Regular function tools and MCP server entries live side-by-side in the same array.

vns_allow_mcp_calls

The AI connects to MCP servers asynchronously after the session starts, which takes a moment. The vns_allow_mcp_calls built-in tool solves the timing problem: when the AI calls it, VNS holds the response and waits for the AI to send back a confirmation that all MCP servers have finished loading. Once VNS receives that signal it unblocks and the AI is clear to use MCP tools.

You must include this tool whenever you use MCP. Without it the AI may attempt to invoke MCP tools before they are available, resulting in errors or missing functionality.

Tool Definition

Add this entry to the tools array in your CallStart response:

{
    "name": "vns_allow_mcp_calls",
    "description": "Call this function to ensure that the mcp servers are ready.",
    "type": "function",
    "parameters": null
}

Example Instruction

Add something like this to your instructions string in the CallStart response so the AI knows to call this tool before using any MCP tools. While it waits, the AI should keep the caller engaged:

Before calling any MCP server tool you MUST first call vns_allow_mcp_calls to verify the MCP server is ready. While waiting for vns_allow_mcp_calls to return, tell the caller something like "One moment please, I'll be right with you" or "Just a moment while I get that ready for you".

MCP Server Configuration

Each MCP server is defined as an entry in the tools array of your CallStart response, identified by "type": "mcp".

{
    "type": "mcp",
    "server_label": "directory",
    "server_url": "https://mcp.voiceelements.com/mcp",
    "headers": {
        "Authorization": "Bearer some-key"
    },
    "allowed_tools": {
        "tool_names": [
            "login",
            "logout",
            "get_all_employees",
            "get_employees_by_department",
            "search_employees",
            "get_employee_by_id",
            "list_departments"
        ]
    },
    "require_approval": {
        "always": {
            "tool_names": [
                "login",
                "get_all_employees",
                "get_employee_by_id"
            ]
        },
        "never": {
            "tool_names": [
                "logout",
                "get_employees_by_department",
                "search_employees",
                "list_departments"
            ]
        }
    }

}

Field Reference

Require Approval

Some MCP tools should not be called automatically — they may modify data, expose sensitive information, or require a human decision. The require_approval field lets you gate specific tools behind an approval step.

Multiple MCP Servers

You can connect more than one MCP server in a single session. Add one entry per server to the tools array, each with its own server_label, URL, headers, and allowed tools. The vns_allow_mcp_calls tool waits for all defined servers to be ready before signaling the AI to continue.

// In your CallStart response tools array:
[
  { "name": "vns_allow_mcp_calls", "type": "function", ... },

  { "type": "mcp", "server_label": "directory",  "server_url": "https://...", ... },
  { "type": "mcp", "server_label": "scheduling", "server_url": "https://...", ... },

  { "name": "vns_end_conversation", "type": "function", ... }
]