Genesys MCP

Servidor de Model Context Protocol (MCP) independiente del proveedor para Genesys Cloud.

genesys-mcp es un servidor de Model Context Protocol (MCP) que expone las capacidades de la plataforma Genesys Cloud —colas, conversaciones, usuarios, presencia, analíticas— como herramientas, recursos y prompts de MCP. Cualquier agente de IA compatible con MCP puede comunicarse con Genesys a través de él: Claude Desktop, Claude Code, Cursor, Continue, Cline y cualquier agente personalizado construido sobre LangGraph, LangChain, CrewAI, AutoGen o un SDK de proveedor nativo.

Estado

v0.1.0 — pre-lanzamiento. El framework, los transportes y la capa de fiabilidad están implementados. El primer lote de herramientas de solo lectura llegará en la v0.2; las escrituras seleccionadas (detrás de --enable-writes) y los Recursos/Prompts llegarán en la v0.3. El lanzamiento de la v1.0 incluirá todo junto con PyPI, Docker (GHCR), un shim de npx y un paquete MCPB.

Related MCP server: agent-notify

Por qué

El ecosistema MCP ya cuenta con un servidor de Genesys Cloud, pero se distribuye solo con stdio sin transporte HTTP, no tiene contexto de autenticación por solicitud (un booleano global del módulo controla todo el proceso) y no tiene una capa de fiabilidad de producción (sin manejo de 429, sin actualización de tokens, sin registro estructurado). genesys-mcp está diseñado para la superficie de producción: HTTP transmitible listo para alojamiento, autenticación por solicitud, reintento consciente de 429, actualización en 401, registros estructurados y rastreo de OpenTelemetry — todo desde el primer día, todo independiente del proveedor.

Inicio rápido

Las herramientas aún no se han enviado; estos fragmentos muestran el patrón de instalación. La v0.2 listará la superficie de herramientas real aquí.

Claude Desktop

Agregue una entrada bajo mcpServers en su claude_desktop_config.json:

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

Claude Code o Cursor

Agregue una entrada a la configuración del servidor MCP de su editor (.claude/settings.json para Claude Code, el panel de configuración de MCP de Cursor para Cursor):

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

Python programático

Conéctese a través del cliente oficial de Python mcp sobre stdio o 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

Para el transporte HTTP, ejecute genesys-mcp --transport http --port 8000 y conecte su cliente MCP a http://localhost:8000.

Instalación

pip install genesys-mcp

Próximamente en la v1.0: publicado en PyPI, GHCR, npm shim y como un paquete MCPB adjunto a los lanzamientos de GitHub.

Transportes

Ambos transportes comparten la misma superficie de herramientas. La selección de transporte está impulsada por el entorno (MCP_TRANSPORT=stdio|http) o por la CLI (--transport).

Seguridad

El transporte HTTP en la v0.x se envía sin autenticación. La capa de encuadre de MCP no realiza ninguna autenticación del llamador; el servidor confía en cualquier proceso que pueda llegar al puerto de escucha. Los operadores tienen dos opciones de despliegue responsables:

1. Vincular solo a 127.0.0.1 (el MCP_HOST predeterminado) y permitir que los agentes locales se conecten a través de loopback.

2. Vincular a una dirección que no sea de loopback solo detrás de un proxy inverso (nginx, Caddy, Cloudflare Access, una puerta de enlace API) que realice la autenticación y autorización antes de reenviar a genesys-mcp.

Vincular a 0.0.0.0 sin una capa de autenticación frontal expone las credenciales de Genesys ascendentes a cualquier persona en la red. Por lo tanto, la imagen de Docker tiene como valor predeterminado MCP_HOST=127.0.0.1; los operadores que realmente necesiten una vinculación pública deben optar explícitamente con -e MCP_HOST=0.0.0.0.

Una puerta de enlace alojada y multi-inquilino con autenticación, auditoría y RBAC de primera clase está en la hoja de ruta Pro/SaaS (ver ADR-006 en docs/warm/decisions.md).

Modelo de confianza

Algunas cosas que debe saber antes de instalar complementos o ejecutar esto en producción:

• Complementos de punto de entrada (el grupo genesys_mcp.plugins) se ejecutan en el proceso del servidor con acceso total a cada dependencia, variable de entorno y credencial de Genesys que tiene el servidor. Solo instale complementos en los que confíe.

• El gancho de licencia (grupo genesys_mcp.license) es una puerta de características, no un control de seguridad. Cualquier paquete instalado puede registrar uno y cualquier complemento puede ignorar la respuesta. Existe para que el paquete Pro pueda expresar derechos; trátelo en consecuencia.

• Los secretos de cliente OAuth se cargan desde variables de entorno (y el archivo .env si está presente) y el servidor mismo nunca los registra. No podemos garantizar lo mismo de los complementos descendentes: revíselos o ejecútelos con LOG_LEVEL=INFO e inspeccione la salida antes de confiarles secretos.

Configuración

La configuración se lee de las variables de entorno (o un archivo .env). Consulte .env.example para obtener la lista completa. Las variables más importantes:

Desarrollo

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 configurará ruff, mypy y una ejecución de pytest previa al push.

Licencia

MIT — ver LICENSE. Copyright 2026 Digital Vanguard Solutions.