Genesys MCP

Genesys Cloud를 위한 벤더 중립적 모델 컨텍스트 프로토콜(MCP) 서버.

genesys-mcp는 Genesys Cloud 플랫폼 기능(큐, 대화, 사용자, 상태, 분석)을 MCP 도구, 리소스 및 프롬프트로 노출하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. Claude Desktop, Claude Code, Cursor, Continue, Cline을 비롯하여 LangGraph, LangChain, CrewAI, AutoGen 또는 원시 공급자 SDK를 기반으로 구축된 모든 사용자 지정 에이전트 등 MCP 호환 AI 에이전트라면 무엇이든 이를 통해 Genesys와 통신할 수 있습니다.

상태

v0.1.0 — 사전 릴리스. 프레임워크, 전송 계층 및 안정성 계층이 마련되었습니다. 첫 번째 읽기 전용 도구 배치는 v0.2에 포함되며, 선별된 쓰기 기능(--enable-writes 옵션 사용)과 리소스/프롬프트는 v0.3에 포함됩니다. v1.0 출시 시 PyPI, Docker(GHCR), npx shim 및 MCPB 번들과 함께 모든 기능이 제공될 예정입니다.

Related MCP server: Genesys Cloud MCP Server

목적

MCP 생태계에는 이미 Genesys Cloud 서버가 존재하지만, HTTP 전송 없이 stdio 전용으로 제공되며 요청별 인증 컨텍스트가 없고(모듈 전역 부울 하나가 전체 프로세스를 제어), 프로덕션 안정성 계층(429 처리, 토큰 새로 고침, 구조화된 로깅 없음)이 부족합니다. genesys-mcp는 호스팅 준비가 완료된 Streamable HTTP, 요청별 인증, 429 인식 재시도, 401 시 새로 고침, 구조화된 로그 및 OpenTelemetry 추적 등 프로덕션 환경을 위해 설계되었으며, 첫날부터 모든 벤더에 중립적으로 작동합니다.

빠른 시작

도구는 아직 제공되지 않았습니다. 아래 코드 조각은 설치 패턴을 보여줍니다. v0.2에서 실제 도구 표면을 나열할 예정입니다.

Claude Desktop

claude_desktop_config.json의 mcpServers 아래에 항목을 추가하세요:

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

Claude Code 또는 Cursor

편집기의 MCP 서버 구성에 항목을 추가하세요(Claude Code의 경우 .claude/settings.json, Cursor의 경우 Cursor MCP 설정 패널):

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

프로그래밍 방식(Python)

공식 mcp Python 클라이언트를 통해 stdio 또는 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

HTTP 전송의 경우 genesys-mcp --transport http --port 8000을 실행하고 MCP 클라이언트를 http://localhost:8000에 연결하세요.

설치

pip install genesys-mcp

v1.0 예정: PyPI, GHCR, npm shim 및 GitHub 릴리스에 첨부된 MCPB 번들로 게시됩니다.

전송 방식

두 전송 방식 모두 동일한 도구 표면을 공유합니다. 전송 선택은 환경 변수(MCP_TRANSPORT=stdio|http) 또는 CLI 옵션(--transport)을 통해 이루어집니다.

보안

v0.x의 HTTP 전송은 인증되지 않은 상태로 제공됩니다. MCP 프레임 계층은 호출자 인증을 수행하지 않으며, 서버는 수신 포트에 도달할 수 있는 모든 프로세스를 신뢰합니다. 운영자는 다음과 같은 두 가지 책임 있는 배포 옵션을 가집니다:

1. 127.0.0.1(기본 MCP_HOST)에만 바인딩하고 로컬 에이전트가 루프백을 통해 연결하도록 합니다.

2. 인증 및 권한 부여를 수행한 후 genesys-mcp로 전달하는 역방향 프록시(nginx, Caddy, Cloudflare Access, API 게이트웨이) 뒤에서만 비루프백 주소에 바인딩합니다.

전면 인증 계층 없이 0.0.0.0에 바인딩하면 네트워크상의 누구에게나 업스트림 Genesys 자격 증명이 노출됩니다. 따라서 Docker 이미지는 기본적으로 MCP_HOST=127.0.0.1로 설정되어 있습니다. 공개 바인딩이 반드시 필요한 운영자는 -e MCP_HOST=0.0.0.0을 사용하여 명시적으로 선택해야 합니다.

일류 인증, 감사 및 RBAC를 갖춘 호스팅된 다중 테넌트 게이트웨이는 Pro/SaaS 로드맵에 포함되어 있습니다(docs/warm/decisions.md의 ADR-006 참조).

신뢰 모델

플러그인을 설치하거나 프로덕션 환경에서 실행하기 전에 알아두어야 할 사항:

• 진입점 플러그인(genesys_mcp.plugins 그룹)은 서버 프로세스 내에서 실행되며 서버가 가진 모든 종속성, 환경 변수 및 Genesys 자격 증명에 대한 전체 액세스 권한을 가집니다. 신뢰할 수 있는 플러그인만 설치하세요.

• 라이선스 후크(genesys_mcp.license 그룹)는 보안 제어가 아닌 기능 게이트입니다. 설치된 모든 패키지는 이를 등록할 수 있으며 모든 플러그인은 응답을 무시할 수 있습니다. 이는 Pro 패키지가 권한을 표현할 수 있도록 존재하므로 그에 따라 처리하십시오.

• OAuth 클라이언트 암호는 환경 변수(및 존재하는 경우 .env 파일)에서 로드되며 서버 자체는 이를 절대 기록하지 않습니다. 다운스트림 플러그인에 대해서는 보장할 수 없으므로, 플러그인을 검토하거나 LOG_LEVEL=INFO로 실행하여 암호를 신뢰하기 전에 출력을 검사하십시오.

구성

구성은 환경 변수(또는 .env 파일)에서 읽어옵니다. 전체 목록은 .env.example을 참조하세요. 가장 중요한 변수는 다음과 같습니다:

개발

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은 ruff, mypy 및 푸시 전 pytest 실행을 연결합니다.

라이선스

MIT — LICENSE를 참조하세요. Copyright 2026 Digital Vanguard Solutions.