Skip to content

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:

  1. Sign in as you always do. Multi-factor authentication and Google or Microsoft sign-in apply.
  2. 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.
  3. Pick the account it will work on — your own, or one under it.
  4. 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_summary returns its time series per day by default. Ask for hourly or 15-minute points, or for the totals alone.
  • report_missed_calls returns 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-ID is 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.