Portal MCP Server¶
Connect an MCP client — Claude Code, Claude Desktop, or anything else that speaks the protocol — to your QVOICE Platform account and let it read and change the account's configuration in plain language.
Ask it "which personas do we have and on what extensions?" and it answers from your account. Ask it to change an AI agent's greeting and it changes it, through the same path the portal uses.
It also builds reports: ask "how many queue calls did each agent answer last week, by day?" and it reads the same numbers the Analytics Hub shows. See Reports.
Note
This is a different surface from the MCP Server an AI agent uses while it is on a call. That one offers the tools a call needs — transfer, hang up, look up a contact. This one offers the tools an administrator needs, and neither is offered the other's.
Connect¶
https://{{ domain }}:9443/api/v2/mcp/portal
Transport is HTTP Streamable. Authenticate with an API key, or sign in from a client that supports it:
| Header | Description |
|---|---|
X-API-Key |
An API key created in your account |
A bearer token works too (Authorization: Bearer <jwt>), which is what a browser-based client uses. Either way the account is resolved on the server — from the key's own record, or from the token — so a client cannot ask about an account it was not issued for.
Working on a sub-account¶
A partner whose key belongs to a parent account can act on one of its children by naming it:
| Header | Description |
|---|---|
X-Account-ID |
The account to work on, if the key's account is above it |
Naming an account the key has no claim to is refused. This is the same check that guards every other endpoint, so what a key can reach here is exactly what it can reach through the API.
claude.ai, ChatGPT and other connectors (sign in, no key)¶
A client that only takes a URL — a custom connector in claude.ai or ChatGPT — signs in instead of sending a key. Give it the address without the port:
https://{{ domain }}/api/v2/mcp/portal
The first time, the app sends you to the portal:
- Sign in as you always do. Multi-factor authentication and Google or Microsoft sign-in apply.
- The portal shows which app is asking, what it will be able to do, and the address it will send you back to. Only allow an app you started connecting yourself.
- Pick the account it will work on — your own, or one under it.
- Select Allow. You are back in the app, connected.
Only an administrator can connect an app. It gets the read-only report tools and, when it asks for them, the configuration tools your role allows (see Tools). The app's access is tied to you: if your user is disabled or your role changes, it follows.
Connected apps are listed in Configuration → API Keys, under Connected apps, with the account each one works on and when it was last used. Revoke ends a connection within a minute. A connection nobody uses for 30 days ends on its own, and every connection asks you to sign in again after 90 days.
Note
In Claude Code, add the server without a key and run /mcp to sign in the same way:
claude mcp add --transport http qvoice-portal https://{{ domain }}/api/v2/mcp/portal
Claude Code¶
claude mcp add --transport http --scope user qvoice-portal \
https://{{ domain }}:9443/api/v2/mcp/portal \
-H "X-API-Key: YOUR_API_KEY"
--scope user makes it available in every project; leave it out to add it only where you run the command.
Any other client¶
Point it at the URL above with the X-API-Key header. Most clients take a JSON block:
{
"mcpServers": {
"qvoice-portal": {
"type": "http",
"url": "https://{{ domain }}:9443/api/v2/mcp/portal",
"headers": { "X-API-Key": "YOUR_API_KEY" }
}
}
}
See API Key Authentication to create the key.
Warning
The key is the scope: it decides which accounts the client may see and change — its own, and any beneath it. Give each person their own; sharing one shares everything it reaches. An administrator's key is required, because these tools do what an administrator does in the portal.
Tools¶
Every administrator gets the report tools, all read-only. The configuration tools below follow the user's role, exactly as the portal does: a tool is offered only when the role allows its section, and is checked again on every call.
| Tools | The role must allow |
|---|---|
| Users | Users → Users (read; create for create_user) |
| Queues | Contact Center → Queues, or Configuration → Queues |
| Campaigns and leads | Contact Center → Campaigns |
| Dispositions | Contact Center → Dispositions |
| CX inboxes | Contact Center → CX Channels |
| Agent states | Contact Center → Agent States |
| Devices | Provisioning → Phones (add, edit, remove) |
| Call flows | Configuration → Call Flows |
| AI personas | AI → Personas (read, create, edit, delete) |
| Moving numbers | Configuration → Phone Numbers |
| SMS providers | Configuration → SMS Provider |
| New accounts, service plans, account features, adding numbers | Configuration → Tenant Accounts / Number Manager / Service Plans, and only for a reseller's administrators |
The built-in Administrator role allows them all. An API key acts as its account's administrator. create_user applies the same rule as the portal: nobody can create a user with more permissions than their own.
Reading the account¶
| Tool | Answers |
|---|---|
get_account_info |
Name, timezone, features, basic configuration, and the account's type (reseller, single_site, organization or location), its parent and its location prefix |
list_users / get_user |
Users, their extensions and status |
list_queues / get_queue |
Queues and how they are configured |
list_devices |
Phones, optionally for one user |
list_callflows |
Call routing |
list_agents / get_agent_states |
Contact centre agents and what they are doing now |
AI personas¶
| Tool | Does |
|---|---|
list_personas |
Every persona: name, job, extension, conversation shape |
get_persona |
One in full — prompt, greeting, voice, extension, gate flow |
create_persona |
Creates one, with an extension and the routing that makes it answer |
update_persona |
Changes prompt, greeting, voice, extension or conversation shape |
Queues¶
| Tool | Does |
|---|---|
create_queue |
Creates one, ready to take calls on an extension |
update_queue |
Changes the roster, the strategy, the ring and wrap-up times |
Campaigns¶
| Tool | Does |
|---|---|
list_campaigns |
Every campaign: queue, type, status, how many leads |
get_campaign |
One in full — queue, retries, cool-off, caller id |
create_campaign |
Creates one against a queue, stopped |
add_campaign_lead |
Adds one lead to dial |
list_campaign_leads |
Where each lead is: waiting, being dialled, cooling off, finished |
set_campaign_status |
Starts, pauses, stops, ends or archives it |
Customer accounts¶
Offered to super admins, and to the administrators of a reseller whose role allows creating accounts. They work as Configuration → Accounts does (see Customer Accounts).
| Tool | Does |
|---|---|
list_service_plans |
The service plans a new account can be given. On an organization or a location, which have no plans of their own, these are the reseller's. |
create_account |
Creates an account under the working account (or account_id): a single site business or, with kind organization, an organization under a reseller; a location under an organization or a single site business. |
create_account takes:
| Argument | |
|---|---|
name * |
Unique on the platform, not ending in a dot. |
timezone * |
IANA timezone, for example America/New_York. |
service_plans |
Plan ids from list_service_plans; the first is the account's plan. Required unless the account is a location, which otherwise takes its organization's plan. |
kind |
Under a reseller only: single_site (default) or organization. |
location_prefix |
Organizations and locations: 1 to 6 digits, not starting with 9, unique in the organization. |
copy_from_parent |
Locations: what to copy from the organization, any of moh, core, callcenter, phone_profiles, separated by commas. Absent: all of them; none: nothing. |
realm |
Default: the name plus the platform domain. |
call_limit, enabled_users, contact_center_users |
Limits, never above the parent's. |
It returns the account's id, name, realm, type and prefix, any warnings (for example a prefix link that was skipped), and what could not be copied. A location created under a single site business turns that business into an organization. Nothing can be created under a location.
Reports¶
Every account administrator can build reports on the account's calls with their own AI client. The report tools only read: none of them changes anything. Each one returns the same data as the matching Analytics Hub report, for the same account and period.
| Tool | Returns | Same as |
|---|---|---|
report_account_summary |
Headline numbers: inbound (answered, missed, unique numbers), outbound (answered, unanswered), missed-call follow-up, talk time, recordings, peak concurrent calls, and a time series | Account Summary |
report_all_calls |
Per user and agent: queue and direct calls, inbound and outbound, answered, missed, talk time | All Calls |
report_queue_stats |
Per queue: total, answered and abandoned calls, talk time, wait before an agent answered, callbacks, transfers, and service level against the queue's SLA | Queues |
report_agent_stats |
Per agent: calls in and out, talk time, and time available, idle, on call, on hold, in wrap-up and not available | Agents Activity |
report_missed_calls |
The missed inbound calls themselves, a page at a time | Missed Calls |
report_inbound_breakdown |
Who handled inbound calls: people, AI agents, or nobody, with a daily series | Inbound Breakdown |
report_outbound_breakdown |
Outbound results for agents and campaigns, per agent and per day, the most-dialled unanswered numbers and the carrier's rejection causes | Outbound Breakdown |
report_call_ratings |
The ratings users gave their calls and the reasons they picked | Call Ratings |
query_calls |
A custom report: filter calls and group them by up to three of direction, call type, queue, agent, remote number, result, hour, day, weekday, week or month | — |
list_report_queues |
The queue names the filters take | — |
get_report_glossary |
What each metric means | — |
Asking for a report¶
Name the period and what you want to see. The assistant chooses the tool.
Give me an overview of last month.
Which agents answered the most queue calls in October, and what was their average talk time?
Show inbound calls per hour of the day for the first week of November, split by answered and unanswered.
Which queue had the worst service level last week?
Periods and time zones¶
- Dates are days (
2026-10-01). The last day is included up to 23:59:59. - Days and hours are counted in the account's time zone, unless the request names another one.
- One request covers at most 92 days. For a longer period, ask for it in parts.
Custom reports with query_calls¶
query_calls covers the calls the account's users and agents handled, queue and direct, inbound and outbound. For each group it returns:
- calls, answered and unanswered
- answer rate
- total and average talk time
- average duration
It can also return up to 200 of the matching calls.
Note
A queue call counts in query_calls only once it rang an agent. A caller who hung up in the queue before any agent rang is in report_queue_stats, whose total and abandoned counts include them. Ask about queue volume and abandonment there.
Limits¶
- A report larger than 400 KB is refused, with a message asking for a shorter period or for
query_calls, which returns totals instead of rows. report_account_summaryreturns its time series per day by default. Ask for hourly or 15-minute points, or for the totals alone.report_missed_callsreturns up to 500 calls per page, 100 by default. The assistant asks for the next page when it needs it.- A report that takes longer than 90 seconds is stopped. Ask for a shorter period.
Sub-accounts¶
A key that belongs to a parent account can report on any account below it. Name the account in the request, or set X-Account-ID (see Working on a sub-account). Asking about any other account is refused.
Creating a persona¶
Four things are required: a name, the job it does, a description, and the prompt that tells it how to behave.
Create a persona called Front Desk that answers our main line, greets
callers in English, finds out who is calling and why, and offers to take
a message when it cannot help.
The persona comes back with an extension already assigned and its inbound routing in place — it can take a call the moment it exists. Name an extension yourself and it is used, unless another callflow already answers it, in which case the request is refused rather than taking the number away from whatever has it.
Note
The greeting is spoken as written. Write the sentence the caller should hear — "Thanks for calling Acme, how can I help?" — not an instruction like "greet the caller warmly", which is what the caller would hear read out.
Changing a persona¶
Only the fields you name are changed; everything else is left alone. Changing a voice does not mean restating the prompt.
Change the Front Desk greeting to "Thanks for calling Acme, how can I help?"
A change made here is the same change the portal makes: the persona's inbound routing is rebuilt to match, and the same rules apply — an extension another callflow already answers is refused, with a message naming what holds it.
Building a queue¶
A queue created here is a queue the portal would create: give it a name, an extension for callers to reach it on, and the people who answer.
Create a queue called sales on extension 9500 with Maria and Carlos as agents.
It can take a call as soon as it exists — the routing that sends its extension to its agents is set up with it.
Agents are named by user id; list_users and list_agents find them. Adding someone later keeps whoever is already in the queue:
Add Sebastian to the sales queue.
There is a separate way to replace the roster outright, which drops anyone not named. Adding and replacing are kept apart on purpose, so "put this person in the queue" cannot quietly remove everyone else.
Setting up a campaign¶
A campaign is an outbound run: it belongs to a queue, takes its agents from that queue, and works through a list of leads. The queue is the part that catches people out. A campaign without one never dials and gives no sign why, so create_campaign refuses to create it rather than leaving you with a campaign that looks fine and does nothing.
The order is: queue, campaign, leads, start.
Create a progressive campaign called Q3 winback on the sales queue,
add 555-0101 as a lead, and start it.
A campaign is created stopped on purpose, so leads can be added before anything rings. set_campaign_status with start is what actually puts them on the phone, and stop takes them off.
Note
set_campaign_status takes an action, not a status. Not every action makes sense from where the campaign is: a running one can be paused or stopped, a stopped one started, paused or ended. Asking for something it cannot do is refused, and the refusal tells you what state it is actually in.
Watch a run with list_campaign_leads. The status says where each lead is: new and selectable are waiting, on_call is being dialled now, cooloff is waiting to be retried, success and failed are finished.
Conversation shape¶
A persona runs a call one of two ways:
| Shape | The call is |
|---|---|
legacy |
One prompt, for the whole conversation |
gate_runtime |
A graph of stages, each with its own prompt and its own tools |
The second is what stops a stage being talked into something it has no business doing: a stage that has no reason to transfer a call is not given the tool to transfer one. Draw the graph in the portal, or pass it as JSON to update_persona. A flow that will not parse, or that names no entry stage, is refused rather than saved for a call to fail on.
Reading a persona returns the flow summarised — its entry stage and the stages in it — because a flow runs to thousands of characters and its shape is usually what you want. Ask for the document itself with include_gate_flow.
What it will not do¶
- Take an account it was not given. The account comes from the key or the token, and an
X-Account-IDis honoured only when the account tree allows it — never on the client's word alone. - Touch a live call. Transferring and hanging up belong to the agent's surface; this one is not offered them.
- Work without an administrator. These tools do what an administrator does in the portal, and the same permission is required.
- Change anything from a report. The report tools only read.