genesys-mcp v0.5.0 - coaching ecosystem (3 new tools + a new skill)
Repo: https://github.com/laggyzee/genesys-mcp · Release: v0.5.0
What's new in v0.5
Three new MCP tools and a second companion skill - cc-coaching-prep - that turns 1:1 prep into a one-prompt HTML brief.
qa_evaluations - first wrapping of /api/v2/quality/*. Per-agent QA scores, pass rates, critical-pass rates, evaluator workload rollup. Needs quality:readonly; soft-fails cleanly without it.agent_coaching_pack - composition tool: performance vs targets, peer-median comparison, sentiment trajectory, QA scores, wrap-up discipline, top flagged calls, heuristic top-3 coaching focus with concrete evidence. Tenant-aware via tenant.yaml.routing_diagnostic - answers "why did this call route the way it did?" for a specific conversation. IVR → queue → agent path with durations, eligible-agent counts (Genesys-provided at routing time), outcome classification, queue routing rules. Supervisors currently spelunk through queue configs and routing flow audit logs for this - now it's one tool call.
And the new skill stitches them together for the use-case that triggered the build: monthly coaching prep.
qa_evaluations - the gap we've been ignoring
The MCP had wrappings for analytics, conversations, WFM, STA, presence, external contacts - but nothing for Quality Management. v0.5 fixes that.
qa_evaluations(user_ids=[...], interval="2026-04-01/2026-05-01")
Returns per-user avg score, pass rate, critical-pass rate, last-evaluated, plus the raw evaluation rows (form, evaluator, score, conversation id). Optional per-question detail + evaluator comments via include_question_detail=True - opt-in because the comments can be PII.
Sharp edge worth knowing about: the Genesys SDK helper get_quality_evaluations_query() returns evaluations with an empty answers block by default. You have to pass expand_answer_total_scores=True to actually get scores back. The MCP tool sets that internally so you don't have to think about it, but anyone building their own integration should know.
agent_coaching_pack - the composition
The headline tool. One call, returns everything a Team Leader needs for 1:1 prep:
{
"agent": {"name": "...", "title": "...", "manager_name": "..."},
"performance": {
"target": {"voice_aht_s": 330.1, "voice_aht_vs_target_pct": 15.8, ...},
"peer_medians": {"voice_aht_s": 319.5, "total_handle_hours": 31.8, ...}
},
"sentiment": {"avg": 0.365, "samples": 56},
"quality": {"scope_available": true, "summary": {"avg_score": 96.3, ...}},
"wrap_discipline": {"note_rate": 0.93, "top_dispositions": [...]},
"flagged_calls": {
"total_flagged": 166,
"top": [
{"conversation_id": "...", "handle_s": 1468, "sentiment_score": -0.82,
"flag_reasons": ["negative sentiment -0.82", "AHT +133% over target"]},
...
]
},
"recommended_focus": [
{"rank": 1, "area": "Message AHT",
"headline": "Message AHT 781s vs target 660s (+18%) - 6.2 handle-hours over target this period"},
...
]
}
The flagged-calls heuristic combines sentiment-drop magnitude, hold ratio, AHT excess, and wrap-up-note presence into a composite flag score. Thresholds come from tenant.yaml.coaching.flagged_call_thresholds - defaults are sane (sentiment drop ≥ 0.5, silent ≥ 30s, AHT ≥ 20% over target).
Gracefully degrades: no quality:readonly → QA section reports scope_available: false; no STA → sentiment empty; the rest always populates.
routing_diagnostic - the supervisor magnet
Pick any conversation_id and get a structured trace:
path:
ivr_or_system 0.1s
ivr_or_system 0.0s
ivr_or_system 40.2s
queue_wait 0.5s | eligible: [3]
agent_handle 146.5s | eligible: [3]
outcome: answered ("Call connected to an agent and was answered.")
timing: 0.5s in queue, 0.5s to first answer
queues_visited: Coles - Retention (29 members / 29 eligible)
Or on an abandoned call you'd see the wait time, the abandon flag, and which queue's eligibility was the problem.
Limitations honest up front: v0.5 ships conversation_id mode only. Aggregate mode ("show me all this week's abandons by failure-mode") is the v0.5.x follow-up - it needs a different endpoint shape. Eligible-agent counts on the path are Genesys-provided session-level (accurate for the moment of the call); the queue-level eligibility_now is current-state and most useful for recent failures.
Companion skill - cc-coaching-prep
Same pattern as cc-monthly-report: one prompt → self-contained HTML. "Prep coaching for Anthony for the last 4 weeks" drops the brief at ~/Documents/coaching-anthony-kha-2026-04.html.
Same visual idiom - colour-coded vs-target pills (+15% warn, +45% bad), peer-comparison badges, KPI cards. Sections:
- Performance vs targets
- Peer comparison (same-role peers, peer-median for each KPI)
- Sentiment & quality (QA scores + sentiment trajectory)
- Wrap-up & handling
- Top flagged calls (heuristic, with transcript-link conversation ids)
- Recommended coaching focus (heuristic top-3)
Talking points (the LLM-synthesised conversation-starter list) come back in chat - not embedded in the HTML, so they stay fresh between runs.
Install
If you ran v0.2+:
cd ~/code/genesys-mcp && git pull && uv sync
# install the new skill
ln -s "$(pwd)/skills/cc-coaching-prep" ~/.claude/skills/cc-coaching-prep
# add the new optional OAuth scope for the QA section to populate
# Genesys Admin → Integrations → OAuth → your client's role → add `quality:readonly`
If you're new:
git clone https://github.com/laggyzee/genesys-mcp.git
cd genesys-mcp
cp .env.example ~/.config/genesys-mcp.env
# edit env file with your client credentials
uv sync
claude mcp add --scope user genesys ~/code/genesys-mcp/run.sh
# install the skills (run genesys-tenant-setup first to populate tenant.yaml)
ln -s "$(pwd)/skills/cc-monthly-report" ~/.claude/skills/cc-monthly-report
ln -s "$(pwd)/skills/cc-coaching-prep" ~/.claude/skills/cc-coaching-prep
ln -s "$(pwd)/skills/genesys-tenant-setup" ~/.claude/skills/genesys-tenant-setup
OAuth scopes (read-only): analytics, conversations, recordings, users, routing, speech-and-text-analytics, workforce-management, external-contacts, quality, presence-definitions:view, audits:audit:view.
What's next
A few candidates for v0.6:
routing_diagnostic aggregate mode - "top abandon causes this week"- LLM-driven narrative synthesis for
cc-monthly-report's 4 hand-written sections
- Outbound campaign performance - large gap, big slice of the community but a separate domain wrapper
------------------------------
Lawrence Drayton
Consultant
------------------------------
Original Message:
Sent: 04-29-2026 19:25
From: Lawrence Drayton
Subject: genesys-mcp: Open-source MCP bridge for Claude Code (Or any LLM, really)→ Genesys Cloud
Hey all!
Posted this over in the general community but might be better here!
I've open-sourced an MCP server I built for my own contact-centre ops work and it's been valuable enough that I figured the wider Genesys community might want it. Sharing here for feedback and to invite contributors.
Repo: https://github.com/laggyzee/genesys-mcp Licence: MIT
What is it
genesys-mcp is a local stdio Model Context Protocol server that exposes a curated, read-only set of Genesys Cloud tools to MCP-compatible AI clients (Claude Code, Cursor, Continue, etc.). Once installed, you can ask the LLM things like:
- "Pull last week's abandon rate by queue"
- "What's the live wallboard look like for these queues?"
- "Find all customers who called us 3+ times this week"
- "Did anyone go over their break or lunch this week?"
- "Pull a quality snapshot for agent X compared to peers"
- "What's the EWT on the Sales queue right now?"
…and the LLM picks the right Genesys API endpoints, makes the calls, and writes up the answer. Everything is read-only - the OAuth client uses Client Credentials with *:readonly scopes, so there's no write surface even via the escape hatch.
It's been replacing a lot of the "log into Admin → run a report → paste numbers into a spreadsheet" loop that ops teams do every day.
How it works
- Python (FastMCP) server running locally over stdio
- Official
PureCloudPlatformClientV2 SDK for typed API access - Generic
call_genesys_api escape hatch for endpoints not yet wrapped, with auto 401 retry - Internal id → name cache (queues, users, wrap-up codes) so most responses come back human-readable
- Multi-region - Sydney, Virginia, Ireland out of the box; trivial to add others
Tool surface
About 35 tools across these areas:
- Directory - list/search queues, users, skills, wrap-up codes; per-user routing status & live presence
- Real-time analytics -
queue_observation, queue_estimated_wait_time (the AI-adjusted-AHT model), queue_performance with derived answered/abandoned/service_level_pct fields that match the Performance UI columns - Conversations - search, full detail, recording metadata, signed media-download URLs
- Presence sessions - break/meal/away analysis wrapping the analytics/users/details async-jobs flow into a single call
- Composition reports -
repeat_caller_report, break_overrun_report, agent_quality_snapshot, live_wallboard (each chains 2–4 endpoints into ops-ready output) - Speech & text analytics (needs
speech-and-text-analytics:readonly) - conversation summaries, sentiment, transcript URLs - External contacts (needs
external-contacts:readonly) - phone/email → CRM record lookup - Workforce management (needs
workforce-management:readonly) - management-unit topology, agent adherence explanations, combined adherence-vs-presence review call_genesys_api - generic escape hatch for any /api/v2/* endpoint
Full table in the README.
Setup (5-min install)
# 1. Clonegit clone https://github.com/laggyzee/genesys-mcpcd genesys-mcp# 2. Create an OAuth Client Credentials client in Genesys Admin# Required scopes: analytics:readonly, conversations:readonly,# recordings:readonly, users:readonly, routing:readonly# Optional: speech-and-text-analytics:readonly, external-contacts:readonly,# workforce-management:readonly# 3. Set env varscp .env.example ~/.config/genesys-mcp.envchmod 600 ~/.config/genesys-mcp.env# edit and paste your client_id, client_secret, region# 4. Install depsuv sync # or: pip install -e .# 5. Wire into your MCP client
For Claude Code, add to ~/.claude/mcp.json:
{ "mcpServers": { "genesys": { "command": "uv", "args": ["run", "--directory", "/path/to/genesys-mcp", "python", "-m", "genesys_mcp.server"], "env": { "GENESYS_CLIENT_ID": "...", "GENESYS_CLIENT_SECRET": "...", "GENESYS_REGION": "ap-southeast-2" } } }}
Restart Claude Code and you're done.
Example sessions
A few real prompts I've used this week:
"Pull EWT for our 6 voice queues right now."
Returns Genesys' own model output (AI-ADJUSTED-AHT formula) per queue per media type.
"Find all customers who called more than 3 times in the last 7 days, group by queue, show connect rate."
Submits the conversation-details async job, paginates, aggregates by ANI, returns ranked list with queue mix.
"Pull a quality snapshot for [agent] vs three peers - flag silent transcripts and excessive holds."
Combines aggregate stats + conversation details + wrap-up note analysis. Detects calls where the auto-summary indicates no recorded dialogue, calls where hold-time exceeded talk-time, and the agent's own-note discipline (% calls with their own notes vs. relying on auto-summary only).
"Did anyone overrun a break or lunch this week, and was it explained in WFM?"
Cross-checks presence sessions (BREAK/MEAL durations vs. configurable targets) against WFM adherence explanations. Flags unexplained overruns separately from approved variance.
Things on the roadmap (PRs welcome)
- Web messaging transcript wrapper (the
/api/v2/conversations/messages/{id}/messages/bulk flow currently needs the escape hatch) - Full async historical adherence (scheduled vs. actual percentages with shift overlay)
- Quality evaluations / scorecards (
quality:readonly) - Outbound campaign progress (
outbound:readonly)
Why share?
Building this saved me probably 5–10 hours a week on routine ops reporting and made it possible to answer things like "show me agents whose wrap-up note discipline dropped this week" in one prompt instead of an afternoon of clicking. If anyone in this community gets the same lift out of it, that's worth more than me keeping it private.
Happy to take questions, PRs, or feedback.
Repo: https://github.com/laggyzee/genesys-mcp
Security note: The OAuth client credentials in this setup connect your MCP server to your tenant. The server runs locally on your machine and stores credentials only in your env vars or a local gitignored .env. Nothing leaves your machine apart from the API calls Claude makes to Genesys on your behalf. Use a dedicated read-only OAuth role per the README - don't reuse a high-privilege client.
#Integrations
#PlatformAPI
#PlatformCLI
#PlatformSDK
------------------------------
Lawrence Drayton
Consultant
------------------------------