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