Genesys MCP

Anbieterneutraler Model Context Protocol-Server für Genesys Cloud.

genesys-mcp ist ein Model Context Protocol (MCP)-Server, der die Funktionen der Genesys Cloud-Plattform — Warteschlangen, Konversationen, Benutzer, Präsenzstatus, Analysen — als MCP-Tools, Ressourcen und Prompts bereitstellt. Jeder MCP-kompatible KI-Agent kann über diesen Server mit Genesys kommunizieren: Claude Desktop, Claude Code, Cursor, Continue, Cline sowie jeder benutzerdefinierte Agent, der auf LangGraph, LangChain, CrewAI, AutoGen oder einem nativen Provider-SDK basiert.

Status

v0.1.0 — Vorabversion. Das Framework, die Transportschichten und die Zuverlässigkeitsebene sind implementiert. Die erste Charge schreibgeschützter Tools erscheint in v0.2; kuratierte Schreibzugriffe (hinter --enable-writes) sowie Ressourcen/Prompts folgen in v0.3. Der v1.0-Launch bündelt alles zusammen mit PyPI, Docker (GHCR), einem npx-Shim und einem MCPB-Bundle.

Related MCP server: agent-notify

Warum

Das MCP-Ökosystem verfügt bereits über einen Genesys Cloud-Server, dieser wird jedoch nur mit stdio ohne HTTP-Transport ausgeliefert, bietet keinen Authentifizierungskontext pro Anfrage (ein einzelner modulweiter boolescher Wert steuert den gesamten Prozess) und besitzt keine produktionsreife Zuverlässigkeitsebene (kein 429-Handling, kein Token-Refresh, kein strukturiertes Logging). genesys-mcp ist für den produktiven Einsatz konzipiert: bereit für gehostetes Streamable HTTP, anfragebasierte Authentifizierung, 429-bewusste Wiederholungsversuche, Refresh-bei-401, strukturierte Protokolle und OpenTelemetry-Tracing — alles von Anfang an und vollständig anbieterneutral.

Schnellstart

Tools sind noch nicht verfügbar — diese Snippets zeigen das Installationsmuster. v0.2 wird hier die tatsächliche Tool-Oberfläche auflisten.

Claude Desktop

Fügen Sie einen Eintrag unter mcpServers in Ihrer claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "genesys": {
      "command": "uvx",
      "args": ["genesys-mcp"],
      "env": {
        "GENESYS_REGION": "mypurecloud.com",
        "GENESYS_CLIENT_ID": "...",
        "GENESYS_CLIENT_SECRET": "..."
      }
    }
  }
}

Claude Code oder Cursor

Fügen Sie einen Eintrag zur MCP-Server-Konfiguration Ihres Editors hinzu (.claude/settings.json für Claude Code, das MCP-Einstellungsfenster für Cursor):

{
  "mcpServers": {
    "genesys": {
      "command": "genesys-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "GENESYS_REGION": "mypurecloud.com",
        "GENESYS_CLIENT_ID": "...",
        "GENESYS_CLIENT_SECRET": "..."
      }
    }
  }
}

Programmatisches Python

Verbinden Sie sich über den offiziellen mcp Python-Client via stdio oder HTTP:

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

params = StdioServerParameters(command="genesys-mcp", args=["--transport", "stdio"])

async with stdio_client(params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        # tools = await session.list_tools()  # available from v0.2

Für den HTTP-Transport führen Sie genesys-mcp --transport http --port 8000 aus und verbinden Sie Ihren MCP-Client mit http://localhost:8000.

Installation

pip install genesys-mcp

Kommt mit v1.0: veröffentlicht auf PyPI, GHCR, npm shim und als MCPB-Bundle, das GitHub Releases beigefügt ist.

Transportschichten

Beide Transportschichten teilen sich dieselbe Tool-Oberfläche. Die Auswahl des Transports erfolgt umgebungsgesteuert (MCP_TRANSPORT=stdio|http) oder über die CLI (--transport).

Sicherheit

Der HTTP-Transport in v0.x wird nicht authentifiziert ausgeliefert. Die MCP-Framing-Ebene führt keine Authentifizierung des Aufrufers durch; der Server vertraut jedem Prozess, der den Port erreichen kann. Betreiber haben zwei verantwortungsvolle Bereitstellungsoptionen:

1. Bindung nur an 127.0.0.1 (der Standard MCP_HOST), damit lokale Agenten über Loopback verbinden können.

2. Bindung an eine Nicht-Loopback-Adresse nur hinter einem Reverse Proxy (nginx, Caddy, Cloudflare Access, ein API-Gateway), der Authentifizierung und Autorisierung durchführt, bevor er an genesys-mcp weiterleitet.

Die Bindung an 0.0.0.0 ohne vorgelagerte Authentifizierungsebene legt die vorgelagerten Genesys-Anmeldedaten für jeden im Netzwerk offen. Das Docker-Image verwendet daher standardmäßig MCP_HOST=127.0.0.1; Betreiber, die zwingend eine öffentliche Bindung benötigen, müssen dies explizit mit -e MCP_HOST=0.0.0.0 aktivieren.

Ein gehostetes Multi-Tenant-Gateway mit erstklassiger Authentifizierung, Audit-Protokollen und RBAC steht auf der Pro/SaaS-Roadmap (siehe ADR-006 in docs/warm/decisions.md).

Vertrauensmodell

Einige Dinge, die Sie vor der Installation von Plugins oder dem produktiven Einsatz wissen sollten:

• Einstiegspunkt-Plugins (die genesys_mcp.plugins-Gruppe) werden im Serverprozess ausgeführt und haben vollen Zugriff auf jede Abhängigkeit, Umgebungsvariable und Genesys-Anmeldedaten, über die der Server verfügt. Installieren Sie nur Plugins, denen Sie vertrauen.

• Der Lizenz-Hook (genesys_mcp.license-Gruppe) ist eine Funktionssperre, keine Sicherheitskontrolle. Jedes installierte Paket kann einen registrieren und jedes Plugin kann die Antwort ignorieren. Er existiert, damit das Pro-Paket Berechtigungen ausdrücken kann; behandeln Sie ihn entsprechend.

• OAuth-Client-Secrets werden aus Umgebungsvariablen (und der .env-Datei, falls vorhanden) geladen und der Server selbst protokolliert sie niemals. Wir können dies für nachgelagerte Plugins nicht garantieren — prüfen Sie diese oder führen Sie den Server mit LOG_LEVEL=INFO aus und inspizieren Sie die Ausgabe, bevor Sie ihnen Geheimnisse anvertrauen.

Konfiguration

Die Konfiguration wird aus Umgebungsvariablen (oder einer .env-Datei) gelesen. Siehe .env.example für die vollständige Liste. Die wichtigsten Variablen:

Entwicklung

git clone https://github.com/digitalvanguardsolutions/genesys-mcp.git
cd genesys-mcp

uv sync --all-extras

uv run pytest
uv run ruff check src tests
uv run mypy src

uv run genesys-mcp --transport stdio

pre-commit install richtet ruff, mypy und einen pytest-Lauf vor dem Push ein.

Lizenz

MIT — siehe LICENSE. Copyright 2026 Digital Vanguard Solutions.