Genesys Cloud MCP Server (read-only)

A minimal MCP server wrapping three read-only Genesys Cloud Platform API calls, meant as the foundation described in ../Genesys-RCA-Agent-Architecture.md. Grow this by adding more @mcp.tool() functions in server.py as the RCA agent needs more signal (agent adherence, IVR flow errors, edge/telephony health, quality evaluations, ...).

Tools included:

• list_queues(name_filter) — resolve a queue name to its id.
• get_queue_aggregates(queue_id, start, end) — SLA%, ASA, abandon %, AHT etc. for a window.
• search_conversations(queue_id, start, end, limit) — conversation-level detail for a window.

Not tested against a live org. The request bodies for the two analytics endpoints follow Genesys Cloud's documented query shape, but Genesys's exact field/metric names have shifted across API versions before. Before wiring this into anything scheduled, run each tool once through the MCP Inspector (step 4) against your real org and fix up any field names that come back wrong — the error message from GenesysApiError will include Genesys's own response body, which usually says exactly what's missing/misnamed.

1. Create a read-only OAuth client in Genesys Cloud

1. Admin → Integrations → OAuth → Add Client.
2. Grant type: Client Credentials.
3. Roles: assign (or create) a custom role with only view-level permissions — at minimum: routing:queue:view, and the relevant analytics:*:view permissions for queue observations, queue aggregates, and conversation details. Do not grant any write/edit permissions — this server has no business needing them, and it removes an entire class of risk if the client secret ever leaks.
4. Save, then copy the Client ID and Client Secret — the secret is only shown once.
5. Note your org's region domain (Admin → Organization Settings, or look at the domain you log in through) — e.g. mypurecloud.com, usw2.pure.cloud, mypurecloud.ie.

2. Local setup

Requires Python 3.10+. (Not currently installed on this machine — grab it from python.org or winget install Python.Python.3.12 if you're setting this up here; a real deployment would run this on a server/container instead anyway.)

cd genesys-mcp-server
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env

Edit .env with the client id/secret/environment from step 1.

3. Sanity-check the Genesys auth call

Before involving MCP at all, confirm the OAuth client works:

python -c "from config import Settings; from genesys_client import GenesysClient; s=Settings.from_env(); c=GenesysClient(s.client_id, s.client_secret, s.environment); print(c.request('GET', '/api/v2/routing/queues', params={'pageSize': 1}))"

If that prints queue JSON, auth and network access are good. If it raises GenesysAuthError, double check the client id/secret/environment. If it raises a 403 on the queues call, the OAuth client's role is missing routing:queue:view.

4. Test the MCP server interactively (no Claude needed yet)

The mcp[cli] package ships an Inspector — a local web UI that lets you call each tool by hand and see the raw response, without wiring up a real MCP client first:

mcp dev server.py

This prints a local URL — open it, and you should see list_queues, get_queue_aggregates, and search_conversations listed as tools. Run list_queues first to get a real queue_id, then try get_queue_aggregates with a recent time window and see whether the response shape matches what the tool's docstring promises. Fix up server.py here before moving on.

5. Connect it to Claude

Claude Desktop — one command registers it:

mcp install server.py --name "Genesys Cloud"

This writes an entry into Claude Desktop's claude_desktop_config.json pointing at this server's venv Python and server.py, and picks up your .env automatically. Restart Claude Desktop and the three tools should show up under the 🔌 icon.

Claude Code (this CLI) — add it as a project or user MCP server:

claude mcp add genesys-cloud -- python "C:\Users\g352280\OneDrive - Principal Financial Group\Ai\Claude\genesys-mcp-server\server.py"

(Run that from a real terminal, not this session — Claude Code reads MCP config at startup.) Or add it by hand to .mcp.json / claude_desktop_config.json:

{
  "mcpServers": {
    "genesys-cloud": {
      "command": "python",
      "args": ["C:\\Users\\g352280\\OneDrive - Principal Financial Group\\Ai\\Claude\\genesys-mcp-server\\server.py"]
    }
  }
}

6. Next steps

• Add the remaining tools from the architecture doc's catalog (agent adherence, IVR flow execution, edge/telephony health, quality evaluations) the same way — one @mcp.tool() function per Genesys endpoint, in server.py.
• Move .env secrets to a real vault (Azure Key Vault) before this runs anywhere but your laptop.
• Once there's more than a couple of tools, consider splitting server.py into one module per Genesys API area (analytics, routing, telephony, quality) and importing them into a single FastMCP instance.