Voicent MCP Server Setup Guide

This guide connects an AI agent, such as Claude, to your own on-premise Voicent Gateway. The agent can then place calls and texts, run campaigns, check results, and read and update CRM records, within the limits you set.

Out of the box it can call or text any number and use the CRM tools, so set your limits before you connect. Campaigns stay off until you turn them on. A tool that's turned off doesn't exist for the agent.

Requires Voicent Gateway 10.10.3 or later.

Contents

1. What you need
2. Protect the gateway
3. Install the server
4. Connect your MCP client
5. Tools
6. Settings
7. Set your limits before you connect
8. Your legal responsibility
9. Known limits
10. Troubleshooting and help

1. What you need

• A Voicent Gateway on your own server, version 10.10.3 or later, with a Workflow license plus Enterprise Edition. For a quote or to check your current license, email sales@voicent.com. Voicent supports Windows 10 and later; the software should also work on older Windows versions.
• An MCP client that can start a local program, such as Claude Code, Claude Desktop, Cursor or VS Code.
• A Windows machine for the MCP server. The build described here is a Windows .exe. If your agent will use audio, import or export files, it has to be the gateway machine.

Your MCP client starts the server on its own machine, and the server sends requests to the gateway. With the default settings, all three run on one machine.

Your dialer and its data live on your server. Whatever your agent reads or sends, such as phone numbers, message text, results and customer records, also passes through the AI client you choose and possibly that client's cloud model. Check that this is acceptable for your data.

License and annual support

The MCP server itself is free. The Workflow license plus Enterprise Edition that it requires is a one-time license. Ask sales@voicent.com for a quote.

Annual support is strongly recommended. It costs 30% of the purchase price per year, with a $99/month minimum. Without support, we won't be able to help you if the software fails to work for any reason.

The licensed software keeps working on the same computer and the same version without support, but there is no technical support, new releases, or license transfer to another computer.

2. Protect the gateway

Keep port 8155 off the internet. Do this before you connect anything.

The limits in this guide apply only to requests that go through the MCP server. Anyone who reaches port 8155 directly can bypass them. The gateway's own interface can do far more than the MCP server allows, including running programs on the gateway machine. Requests from other machines need the gateway's Remote Connect Password, so set your own in Voicent App > Setup > Options > Control on the gateway computer. Some of the gateway's call flow pages have no password check, so a password alone doesn't protect a gateway that others can reach.

• Don't forward port 8155 on your router, and don't open it in a firewall or cloud security group to outside addresses.
• Don't expose the gateway machine's other service ports either.
• From a network outside your own, confirm that port 8155 can't be reached.
• If the MCP server runs on a different machine, connect the two over a private network or VPN, and set the gateway's Remote Connect Password.
• If other people or machines share your network, limit which of them can reach the port.

3. Install the server

Download voicent-mcp.exe from the GitHub release page and put it in a folder of your choice. It runs without Deno.

The examples below use C:\voicent-mcp\voicent-mcp.exe. Replace this with your own path, and always use the full path.

Build from source (optional)

If you have the source, you can test it and build it yourself with Deno:

deno task test      # tests against a fake gateway; nothing is dialed
deno task start     # run from source
deno task compile   # build dist/voicent-mcp.exe, which runs without Deno

4. Connect your MCP client

The setup below works when the gateway is on the same machine. Before you connect: with only these settings, the agent can call or text any number, and read and change CRM records. Add the settings in Set your limits to the env section first. The server repeats these warnings in its log each time it starts.

After connecting, ask your agent to list its Voicent tools, and check that only the tools you expect appear.

Claude Code

Add this to .mcp.json in your project folder. In interactive sessions, Claude Code asks you to approve a server from this file before using it. Non-interactive runs, such as claude -p, load it without asking.

{
  "mcpServers": {
    "voicent": {
      "command": "C:\\voicent-mcp\\voicent-mcp.exe",
      "env": {
        "VOICENT_GATEWAY_URL": "http://localhost:8155"
      }
    }
  }
}

Or add it from the command line, for your use only:

claude mcp add --env VOICENT_GATEWAY_URL=http://localhost:8155 --transport stdio voicent -- C:\voicent-mcp\voicent-mcp.exe

Check the connection with claude mcp list, or /mcp inside Claude Code.

Claude Desktop

1. Open Settings from the Claude menu, select Developer, then click Edit Config. This opens %APPDATA%\Claude\claude_desktop_config.json.
2. Add the same voicent entry shown above under mcpServers. Keep any other servers already listed there.
3. Quit Claude Desktop completely and start it again.

If the server doesn't appear, check the logs in %APPDATA%\Claude\logs, starting with mcp.log and mcp-server-voicent.log.

Cursor

Add this to .cursor/mcp.json in your project, or to ~/.cursor/mcp.json to use it in all projects:

{
  "mcpServers": {
    "voicent": {
      "type": "stdio",
      "command": "C:\\voicent-mcp\\voicent-mcp.exe",
      "env": {
        "VOICENT_GATEWAY_URL": "http://localhost:8155"
      }
    }
  }
}

VS Code

Add this to .vscode/mcp.json in your workspace, or to your user mcp.json. VS Code uses servers as the top-level key, not mcpServers.

{
  "servers": {
    "voicent": {
      "type": "stdio",
      "command": "C:\\voicent-mcp\\voicent-mcp.exe",
      "env": {
        "VOICENT_GATEWAY_URL": "http://localhost:8155"
      }
    }
  }
}

Use the MCP: List Servers command to start, restart or view the output of the server.

Other MCP clients

Any client that can start a local MCP server needs the same three things: the command (the full path to voicent-mcp.exe), the environment variables, and a server name. See your client's documentation for its file format. This guide covers local setups only, so a client that can only connect to a server by URL can't use these steps.

If the gateway is on another machine

Set VOICENT_GATEWAY_URL to the gateway's private address, and set VOICENT_PASSWORD to the gateway's Remote Connect Password, set on the gateway computer in Voicent App > Setup > Options > Control. If you use a user's password instead, also set VOICENT_USERNAME to that user's login name. File tools won't work in this setup, because the gateway reads file paths on its own machine.

Don't put passwords in a file you commit to source control. Use the client's own method instead:

• Claude Code: "VOICENT_PASSWORD": "${VOICENT_PASSWORD}" reads the value from an environment variable.
• Cursor: "VOICENT_PASSWORD": "${env:VOICENT_PASSWORD}" does the same.
• VS Code: use a ${input:...} variable, which prompts for the value and stores it securely.

5. Tools

With the default settings, 14 of the 20 tools are on: the three status tools, the five call and text tools, and the six CRM tools. Tools that use audio, import or export files also need VOICENT_FILE_ROOT. Check Known limits before relying on call_ivr, campaign_run_email, or CRM lookups by phone number or email.

6. Settings

Set these in the env section of your client's configuration.

7. Set your limits before you connect

By default, the agent can call or text any number, and read and change CRM records. Decide what it may do, and add those settings to the env section before you connect.

We recommend turning things on one at a time, and testing each before going further. These steps reduce risk but don't remove it.

Step 1: Test the connection with calls and CRM off

"env": {
  "VOICENT_GATEWAY_URL": "http://localhost:8155",
  "VOICENT_ALLOW_CALLS": "0",
  "VOICENT_ALLOW_CRM": "0"
}

Confirm that only the three status tools appear: call_status, campaign_status and import_status.

Step 2: Allow calls and texts to your own test number

Remove VOICENT_ALLOW_CALLS, and replace YOUR_TEST_NUMBER with a phone you control. Then restart your client or the server.

"env": {
  "VOICENT_GATEWAY_URL": "http://localhost:8155",
  "VOICENT_ALLOWED_NUMBERS": "YOUR_TEST_NUMBER",
  "VOICENT_ALLOW_CRM": "0"
}

Ask your agent to send a short text to that number, then to check the result. After that, ask it to text a second phone you control that isn't on the list, and confirm that the request is refused. Never use someone else's number for this test.

Add numbers only as you need them. Without VOICENT_ALLOWED_NUMBERS, the agent can call or text any number, so leave it out only if that is what you want.

Step 3: Turn on the CRM tools when the agent may read and change customer records

Remove VOICENT_ALLOW_CRM, then restart. Before you do, note how these tools work:

• CRM reads send customer records to your AI provider, and CRM writes change them.
• Only known fields can be read or changed.
• The CRM tools can set DO_NOT_CALL and DO_NOT_EMAIL to yes, but only a person can clear them. List imports are different; see Step 4.
• crm_add_or_update only fills empty values, unless the agent sets overwrite to true.
• Notifications from crm_notify_agent are plain text.
• The agent can't search or list records. It needs a record's ID, or a customer's phone number or email.

Test first with a record you created for testing.

Step 4: Turn on campaigns only where a full-list send is acceptable

VOICENT_ALLOWED_NUMBERS does not apply to campaigns. A campaign contacts everyone on its list.

"env": {
  "VOICENT_GATEWAY_URL": "http://localhost:8155",
  "VOICENT_ALLOWED_NUMBERS": "YOUR_TEST_NUMBER",
  "VOICENT_ALLOW_CAMPAIGNS": "1",
  "VOICENT_FILE_ROOT": "C:\\voicent-mcp\\files"
}

Keep VOICENT_ALLOWED_NUMBERS from Step 2 until you decide the agent may call any number.

• List imports aren't limited like the CRM tools. campaign_import_list can update any column of matching contacts, including clearing DO_NOT_CALL, from a file in VOICENT_FILE_ROOT. Only put files there that you'd import yourself.
• Point VOICENT_FILE_ROOT at a folder that holds only files the agent may use. Don't use a drive root or a user profile folder.
• Run the server on the gateway machine if you need to import lists or use audio files.
• Test first with a small list of your own numbers.
• Review each list before a campaign runs. Check that everyone on it may be contacted.

Habits that help

• Keep approval prompts on. Where your client asks before using a tool, don't auto-approve calling, CRM or campaign tools.
• Turn off what a setup doesn't need. In configurations that don't need them, including shared project files, set VOICENT_ALLOW_CALLS and VOICENT_ALLOW_CRM to 0, and leave campaign settings out.
• Be careful what a calling-enabled agent reads. Text in a web page, email or document can try to steer an AI agent. Don't have it process untrusted content in the same session.

What the server blocks

• Requests are built from a fixed set of fields. The server never sends the gateway fields that run programs, run database queries, start VoiceXML or a URL, or bypass do-not-call.
• Phone numbers must be a single number in a strict format. This blocks the gateway's special number values.

These limits protect against mistakes through the MCP server. They don't protect a gateway exposed to the network, and they aren't a do-not-call or legal compliance feature.

8. Your legal responsibility

You are responsible for making sure your calls, texts and emails are lawful, including when an AI agent starts them. Nothing in this software or this guide makes your calling legally compliant, and this guide isn't legal advice.

• Rules on consent, do-not-call lists, automated or artificial voice calls, texts, caller ID, calling hours and marketing email vary by country and state. Get advice for the places you call.
• Have the consent you need, and honor opt-outs and do-not-call requests, before anyone is added to a list.
• An agent can make a mistake quickly and at scale. You remain responsible for what it sends.

In this setup, the AI agent operates the dialer. This guide isn't about having AI voices talk to the people you call, and we don't promote that use. call_text reads your text to the person called using text-to-speech, so rules on automated or artificial voice calls can apply to it.

9. Known limits

Not included

• Predictive dialer campaigns
• Scheduled or recurring campaigns
• Uploading files to a remote gateway
• Searching, listing or deleting CRM records. Without search, the agent needs a record's ID, or a customer's phone number or email.

Known issues

• Phone and email lookups can match the wrong record when there are duplicates. Use the record ID when you have it.
• call_ivr can't check that an app is outbound. Use outbound apps only. It refuses names that aren't deployed.
• An IVR app with no answering machine message can occasionally end as failed when it reaches voicemail. Add the message to the app in IVR Studio.
• Test email campaigns with your own addresses first. campaign_run_email needs an outgoing email account saved on the gateway, named by its address in smtp_account.
• File tools only work when the server runs on the gateway machine, because the gateway reads the file paths.

10. Troubleshooting and help

For licensing and quotes, email sales@voicent.com. For other product help, see Voicent Support. The gateway's own interfaces are described in the developer documentation.