# Voicent MCP server

Lets an AI agent use an on-premise Voicent Gateway: place calls and texts, run campaigns, check results, and read and update CRM records.

This is phase 1, covering the Simple Gateway API, the Campaign API and the CRM API. Anything that needs a product change, such as CRM search, comes in phase 2.

**Requires Voicent Gateway 10.10.3 or later.** On older versions, audio calls fail, Chinese text is lost when a request is saved, and apostrophes in customer fields are saved wrongly.

**Voicent licenses:** you need the Workflow license plus the Enterprise Edition of the product.

## Tools

Single calls, texts and CRM tools are on by default, and campaigns are off. A tool that's turned off doesn't exist for the agent.

| Setting | Tools |
|---|---|
| Always on | `call_status`, `campaign_status`, `import_status` |
| On unless `VOICENT_ALLOW_CALLS=0` | `call_text`, `call_audio`, `call_ivr`, `send_sms`, `call_remove` |
| On unless `VOICENT_ALLOW_CRM=0` | `crm_get_field`, `crm_add_or_update`, `crm_set_field`, `crm_add_note`, `crm_schedule_callback`, `crm_notify_agent` |
| Off unless `VOICENT_ALLOW_CAMPAIGNS=1` | `campaign_import_list`, `campaign_upload_audio`, `campaign_export`, `campaign_run_autodialer`, `campaign_run_text`, `campaign_run_email` |

Not included yet: predictive dialer campaigns, scheduled or recurring campaigns, uploading files to a remote gateway, and searching, listing or deleting CRM records. Without search, the agent needs a record's ID, or a customer's phone number or email.

## Settings

| Variable | Purpose |
|---|---|
| `VOICENT_GATEWAY_URL` | Gateway address. Default: `http://localhost:8155` |
| `VOICENT_ALLOW_CALLS` | `0` turns off single calls and texts. Default: on |
| `VOICENT_ALLOWED_NUMBERS` | Limits single calls and texts to these comma-separated numbers. Default: any number |
| `VOICENT_ALLOW_CRM` | `0` turns off the CRM tools. Default: on |
| `VOICENT_ALLOW_CAMPAIGNS` | `1` turns on campaigns and list imports |
| `VOICENT_FILE_ROOT` | Folder that audio, import and export files must stay inside. File tools refuse to run without it |
| `VOICENT_PASSWORD` | The gateway's Remote Connect Password, needed when the gateway isn't on this machine |
| `VOICENT_USERNAME` | Login name, if `VOICENT_PASSWORD` is a user's password instead of the Remote Connect Password. In cloud-service mode, the account owner uses `admin`, not an email address |
| `VOICENT_ACCOUNT_ID` | Account ID (`cc_card_id`), needed only for a gateway in cloud-service mode |
| `VOICENT_TIMEOUT_MS` | Request timeout. Default: 30000 |

File paths are read by the gateway, so file tools only work when this server runs on the gateway machine.

## Safety

- **By default, the agent can call or text any number.** To limit it, for example while testing, set `VOICENT_ALLOWED_NUMBERS`. To turn calls and texts off, set `VOICENT_ALLOW_CALLS=0`.
- **`VOICENT_ALLOWED_NUMBERS` does not apply to campaigns.** A campaign contacts everyone on its list, so only turn on `VOICENT_ALLOW_CAMPAIGNS` where that's acceptable.
- **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.
- **CRM reads send customer records to your AI provider, and CRM writes change them.** To turn the CRM tools off, set `VOICENT_ALLOW_CRM=0`.
- **Limits on CRM tools:** only known fields can be read or changed. The agent can set `DO_NOT_CALL` and `DO_NOT_EMAIL` to yes, but only a person can clear them. `crm_add_or_update` only fills empty values unless `overwrite` is true. Notifications are plain text.
- **Protect the gateway itself.** These limits only apply to this server. The gateway is open from localhost and needs its Remote Connect Password from anywhere else. **Set your own in Voicent App > Setup > Options > Control,** because a remote login can deploy IVR apps and run SQL. Don't expose the port to untrusted networks. Some call flow pages have no password check.
- Requests are built from a fixed set of fields. The server never sends `sql` or database fields, `startvxml` or `starturl`, or `ignorednc` (this bypasses do-not-call).
- Phone numbers must be a single number in a strict format, which blocks the gateway's special values `dbquery`, `dialer` and `vcenter`.

## Run

Requires [Deno](https://deno.com).

```
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
```

## Connect to Claude Code

Add this to `.mcp.json`:

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

**Before you connect:** with this config, the agent can call or text any number, read CRM records, which go to your AI provider, and change them. Add settings to `env` to change that:

| To | Add |
|---|---|
| Limit calls and texts to certain numbers | `"VOICENT_ALLOWED_NUMBERS": "650-555-0100,650-555-0101"` |
| Turn calls and texts off | `"VOICENT_ALLOW_CALLS": "0"` |
| Turn the CRM tools off | `"VOICENT_ALLOW_CRM": "0"` |
| Turn campaigns on | `"VOICENT_ALLOW_CAMPAIGNS": "1"` |
| Allow audio, import and export files | `"VOICENT_FILE_ROOT": "C:\\voicent-files"` |

The server repeats these warnings in its log each time it starts.

## Differences from the developer docs

The server sends what the gateway actually reads, which differs from the developer docs in these places:

- Email campaigns pass inline content as `msginfo` (subject) and `msgbody` with no `msgtype`. The docs describe `msgtype=file` and `msgfilepath`, which the gateway doesn't read.
- `call_ivr` uses the `startapp` field.
- Every request sends the password as `agent_password`, with `agent_username` for a user login. The docs use `passwd` for the Remote Connect Password, and the gateway accepts it under either name.

## 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.** It refuses names that aren't deployed. Use outbound apps only.
- **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.

## License

This server is under the MIT License; see `LICENSE`. The Voicent software it connects to is licensed separately.