genesys-cloud-mcp

Most questions a supervisor asks about a contact center are simple to say and slow to answer: which queue is losing calls this morning, who handled the most chats yesterday, what happened to a specific call. In Genesys Cloud the answer is usually spread over a few analytics views and filters. An AI assistant with access to the Platform API could answer them directly, but giving it a token that can also change routing, or read every customer's phone number, is not something most teams want.

This is a Model Context Protocol server that gives the assistant 31 tools over queues, agents, conversations, channels, IVR and bot flows, opening hours, quality evaluations, surveys, workforce management schedules, callbacks, outbound campaigns, teams, routing setup and the audit log, and nothing that writes. Every request goes through a read-only check before it is sent, and customer names, numbers and email addresses are masked by default. It includes a simulated contact center, so it can be tried in any MCP client without a Genesys Cloud account.

Four tool calls against the demo contact center, shown as tables by npm run try. The model receives the same data as JSON.

What you can ask

• How are the queues doing right now? Is anyone waiting?

• Which queue missed its service level yesterday, and in which hours?

• Who handled the most interactions this week and what is their average handle time?

• Show me the abandoned chats from the last 4 hours that waited more than two minutes.

• Walk me through conversation 284d0a28-...: how long did the customer wait, was there a hold, how did it end?

• Is Billing doing better or worse than last Tuesday at this time?

• How much of the morning were the Billing agents actually on queue, and when did they take lunch?

• What was Karen doing between 10:00 and 11:00?

• How many callers finished in the IVR without talking to anyone, and how many hung up in the menus?

• Are we open on the 2nd of November? When do we close today?

• What wrap-up codes did Retention use this week, and how often did they save the cancellation?

• Who is out of adherence right now, and for how long?

• Were we short of the schedule in Billing yesterday morning, or was the schedule itself too thin?

• What is Emma's average quality score this month, and did she fail any critical questions?

• What did the detractors say about Support this week?

• How many callbacks are waiting, and how long did customers wait to be called back today?

• How far along is the upgrade campaign, and what is its connect rate?

• How much of today's volume came in on WhatsApp, and how is its service level compared with voice?

• What do customers ask the bot that it does not understand?

• Who can take Spanish calls right now?

• Which team has the best quality score and NPS this week?

• Did anyone change the Billing queue or the IVR in the last few days?

Related MCP server: WorkForceAI MCP Server

Tools

Queues

Agents

Conversations

Flows and opening hours

Quality and surveys

Workforce management

Callbacks and outbound

Channels and bots

Routing setup

Teams

Change history

Prompts combine the tools for common tasks:

Queues, agents and flows can be given by name; partial names work ("chat" finds Chat Support). Intervals accept today, yesterday, this_week, last 30m, last 4h, last 7d or an ISO-8601 interval. Calendar words use GENESYS_TIMEZONE.

Results are JSON with names instead of ids, durations in seconds (or minutes where the field says so) and rates as percentages, so the model does not have to convert milliseconds or look up ids.

Try it with the demo contact center

The demo is a fictional center with six queues (voice and messaging), 25 agents in five teams and three entry flows. Calls and messages arrive on a daily curve, go through the IVR or the messaging bot, and are routed to the first free agent who is on shift and not on lunch or a break, so waits, abandons and service level come out of the load and staffing. Some callers finish in self-service or hang up in the menus, and outside opening hours they hear the closed message. In three queues, callers about to hang up can ask for a callback. The opening hours have weekday and weekend schedules, a closed slot for a team meeting and the local holidays.

Agents work published shifts with two breaks and lunch, and do not follow them exactly: some log in late, some breaks run over, and a call that runs into a break delays it. Two supervisors evaluate about one in 25 interactions, about 30% of customers get a survey and a third of them answer, some with a comment. Sales and Retention run outbound campaigns. Messages come in on web messaging, WhatsApp and Facebook, the bot recognises a handful of intents and misses some messages, and the audit log has two weeks of configuration changes. History covers the last five weeks and live status changes as the day goes on.

In Claude Desktop, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "genesys-cloud-demo": {
      "command": "npx",
      "args": ["-y", "github:oebh2408/genesys-cloud-mcp", "--demo"]
    }
  }
}

In Claude Code:

claude mcp add genesys-cloud-demo -- npx -y github:oebh2408/genesys-cloud-mcp --demo

Or from a clone:

npm install
npm run try                 # calls three tools and prints the results as tables
npm run inspector           # opens the MCP Inspector against the demo

This is what the model receives from get_queue_performance for the demo Billing queue on a bad morning:

{
  "interval": "2026-10-20T05:00:00.000Z/2026-10-20T16:40:00.000Z",
  "timeZone": "America/Bogota",
  "serviceLevelTargetSeconds": 20,
  "queues": [
    {
      "queue": "Billing",
      "offered": 87,
      "answered": 60,
      "abandoned": 19,
      "abandonRatePercent": 21.8,
      "serviceLevelPercent": 58.9,
      "avgSpeedOfAnswerSeconds": 23,
      "longestWaitSeconds": 254,
      "avgAbandonSeconds": 67,
      "avgHandleSeconds": 309,
      "avgTalkSeconds": 250,
      "avgHoldSeconds": 67,
      "avgAcwSeconds": 35,
      "transferred": 1,
      "leftForCallback": 8
    }
  ]
}

Connect to a real org

1. In Genesys Cloud, create a role with view permissions only. The tools need:

   • analytics:conversationAggregate:view

   • analytics:conversationDetail:view

   • analytics:queueObservation:view

   • analytics:userAggregate:view

   • analytics:userDetail:view

   • analytics:flowAggregate:view

   • routing:queue:view

   • routing:wrapupCode:view

   • routing:skill:view

   • architect:flow:view

   • architect:schedule:view

   • architect:scheduleGroup:view

   • analytics:evaluationAggregate:view, quality:evaluation:view

   • analytics:surveyAggregate:view, quality:survey:view

   • wfm:realtimeAdherence:view, wfm:schedule:view, wfm:agent:view, wfm:activityCode:view

   • outbound:campaign:view

   • analytics:botFlowReportingTurn:view for bot turns

   • directory:team:view, authorization:division:view

   • audits:audit:view

   • permission to view users, their presence and routing status

   Permission names change from time to time; check them in Admin > Roles / Permissions. A 403 from a tool tells you which request was refused.

2. Create an OAuth client with the Client Credentials grant and assign it that role, restricted to the divisions you want the assistant to see.

3. Configure the server:

{
  "mcpServers": {
    "genesys-cloud": {
      "command": "npx",
      "args": ["-y", "github:oebh2408/genesys-cloud-mcp"],
      "env": {
        "GENESYS_CLIENT_ID": "...",
        "GENESYS_CLIENT_SECRET": "...",
        "GENESYS_REGION": "mypurecloud.com",
        "GENESYS_TIMEZONE": "America/Bogota"
      }
    }
  }
}

Safety

Library

The server can be embedded, for example to run it over a different transport or to point it at another implementation of the API:

import { createServer, HttpPlatformClient } from 'genesys-cloud-mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const client = new HttpPlatformClient({ clientId, clientSecret, region: 'mypurecloud.com' });
const server = createServer({ client, timeZone: 'America/Bogota' });
await server.connect(new StdioServerTransport());

PlatformClient is a single request(method, path, options) method. DemoPlatformClient implements it with the simulated center, which is also what the tests use.

Limits

• Directory lookups (queues, users, wrap-up codes, flows) read up to 2,000 entries each and are cached for five minutes.

• search_conversations returns at most 100 conversations per call and uses the synchronous details query, which Genesys Cloud limits to recent intervals. Large exports belong in an analytics job, not in a chat.

• Service level is reported as computed by Genesys Cloud for each queue; the 20 second target shown in results is the demo's setting.

• Queue observations are per queue. An agent who is a member of several queues is counted in each.

• get_agent_timeline reads up to 100 interactions per call and covers at most seven days.

• get_schedule_status evaluates schedules itself. It understands one-off schedules and RRULEs with FREQ daily, weekly (BYDAY), monthly (BYMONTHDAY) or yearly, INTERVAL and UNTIL; other rule parts are ignored. The next change is found to the minute within eight days.

• get_adherence is real time only. Historical adherence in Genesys Cloud is an asynchronous report and is not covered.

• Schedule searches that Genesys Cloud answers asynchronously (large management units or long periods) are not supported yet; the tool says so instead of guessing.

• list_survey_responses reads the newest 100 conversations with an answered survey and then each survey for its comment, so it is meant for recent samples, not exports.

• The quality, survey, workforce management and outbound tools follow the Platform API documentation and are tested against the demo org, which implements the same requests. Field names in a real org can differ in details; please open an issue if one does.

• get_bot_performance reads up to 5,000 bot turns per bot; for long intervals the intent counts are a sample and the result says it was truncated.

• get_recent_changes uses the real-time audit query, which covers the last 14 days. Older changes need the asynchronous audit query, which is not supported.

• get_team_performance groups by supervisor using the manager set on each user, so it is only as good as that field.

• The channel, bot, routing, team and audit tools are tested against the demo org only, like the quality and workforce tools above.

• endedInFlow in get_flow_performance does not separate self-service from callers who hung up; flow outcomes do, if the flows set them.

Design decisions

• 0001 · Read-only tools only

• 0002 · Demo org behind the same client interface

• 0003 · Shape results for the model, not the API

Development

npm install
npm test         # tools against the demo org, the read-only check, masking, and the server over stdio
npm run try -- get_queue_status '{"queues":["Support"]}'   # one tool, raw JSON
npm run demo:svg # re-renders docs/demo.svg from npm run try, with the clock pinned

License

MIT © Oscar Benavides

Not affiliated with or endorsed by Genesys. Genesys Cloud is a trademark of its owner.