☎️ five9-mcp

당신의 Five9 컨택센터, 이제 AI의 손에.

Claude, ChatGPT, 또는 모든 MCP 클라이언트를 Five9 클라우드 컨택센터에 연결하는 오픈소스 MCP 서버 — Cloudflare Workers에서 **제로 의존성(zero dependencies)**으로 실행됩니다.

빠른 시작 · Claude 연결 · ChatGPT 연결 · 도구 · 아키텍처

AI에게 이렇게 물어보세요:

"지금 통화 중인 사람은 누구고, 영업 큐는 어느 정도 밀려 있나요?" 📊 "재유치(win-back) 목록용 프리뷰 캠페인을 만들고, 영업 스킬을 연결한 다음 시작하세요." 🛠️ "OUTBOUND_AGED 캠페인을 중지하고 이 리드 3건을 콜백 목록에 추가하세요." 📞 "새 상담원을 온보딩하세요: 사용자를 만들고 결제(billing) 스킬을 레벨 2로 할당하세요." 🧑💼 "555-867-5309가 우리 DNC 목록에 있나요? 누가 전화를 걸기 전에 확인해 주세요." 🚫 "어제의 Call Log 리포트를 가져와서 포기율(abandon rate)을 요약해 주세요." 📈 "완전한 IVR을 만들어 주세요: 1번은 스케줄링, 2번은 결제, 근무 시간 외에는 음성사서함으로 연결하세요." 🧩

내부적으로 이 서버는 Five9의 Configuration(관리자) 및 Statistics(슈퍼바이저) SOAP 웹 서비스 — Five9 관리자 화면을 여전히 구동하는 API — 와 통신하며, 이를 MCP streamable HTTP 위에서 깔끔한 JSON 도구로 노출합니다. 직접 작성한 봉투(envelope), 약 60줄짜리 XML 파서, npm 패키지 없음. 모든 도구는 실제 Five9 도메인에서 검증되었습니다.

✨ 내장 웹 UI

배포하면 Worker가 API 이상의 것을 제공합니다:

콘솔은 자격 증명을 확인하고, 각 도구가 반환하는 결과를 탐색하고, 캠페인을 디버깅하는 가장 빠른 방법입니다 — AI 없이도 가능합니다.

🚀 빠른 시작 — 터미널 필요 없음

무료 Cloudflare 계정과 API 액세스 권한이 있는 Five9 사용자가 필요합니다 — AI가 수행하길 원하는 범위로 전용 Five9 API 사용자를 만들고, 개인 관리자 로그인을 재사용하지 마세요.

1 — Cloudflare에 배포 (브라우저에서 한 번의 클릭으로)

Cloudflare에 로그인하고 안내를 따라 클릭하세요 — 이 Worker의 복사본(필요한 KV 네임스페이스 포함)이 생성되고 https://five9-mcp.you.workers.dev 같은 URL이 제공됩니다.

2 — 설정 마법사 실행 (브라우저에서)

새 서버에서 **/setup**을 엽니다. Five9 사용자 이름, 비밀번호, 리전을 입력하세요 — 마법사는 저장하기 전에 Five9에 대해 실시간으로 검증한 다음, 액세스 키를 전달합니다(한 번만 표시됩니다 — 비밀번호 관리자에 저장하세요).

3 — AI 연결 (아래 안내 참조), 그런 다음 *"연결을 확인하고 내 캠페인 목록을 보여줘."*라고 요청하세요. 🎉

git clone https://github.com/ryanshatz/five9-mcp
cd five9-mcp
npx wrangler deploy   # provisions the CONFIG KV namespace on first deploy

그런 다음 /setup 마법사를 사용하거나, 건너뛰고 Wrangler secrets로 자격 증명을 관리하세요(secrets가 마법사보다 우선합니다):

npx wrangler secret put FIVE9_USERNAME   # e.g. apiuser@yourdomain
npx wrangler secret put FIVE9_PASSWORD
npx wrangler secret put MCP_AUTH_TOKEN   # a long random string — this is the key to your server

기본값은 wrangler.toml에 있으며 미국 도메인에서 작동합니다:

🔌 AI 연결하기

Claude 연결 (웹 및 데스크톱)

커스텀 커넥터는 Free(커넥터 1개), Pro, Max, Team, Enterprise 플랜에서 사용할 수 있습니다.

1. claude.ai 또는 Claude 데스크톱 앱에서 Settings → Connectors를 엽니다.

2. Add custom connector를 클릭합니다.

3. 이름을 Five9로 지정하고 서버 URL을 /mcp 경로를 포함하여 붙여넣으세요: https://<your-worker>.workers.dev/mcp

4. Add를 클릭한 다음 Connect를 클릭합니다. Claude가 이 서버에 내장된 OAuth를 자동으로 발견하고 인증 페이지를 엽니다.

5. 🔐 five9-mcp 화면에서 액세스 키로 MCP_AUTH_TOKEN을 붙여넣고 Authorize를 클릭합니다.

6. 아무 채팅에서 search & tools (＋) 메뉴를 열고 Five9 커넥터가 켜져 있는지 확인합니다.

Team/Enterprise: Owner(소유자)가 먼저 Organization settings → Connectors에서 커넥터를 추가합니다. 그러면 멤버가 자신의 설정에서 Connect를 클릭하여 인증합니다.

ChatGPT 연결

커스텀 MCP 커넥터는 Developer mode가 필요합니다(Plus/Pro; Business/Enterprise에서는 관리자가 커스텀 커넥터를 허용해야 합니다).

1. 웹의 ChatGPT에서 Settings → Apps & Connectors(때로는 Connectors로만 표시됨)를 엽니다.

2. Advanced settings 아래에서 Developer mode를 켭니다.

3. Connectors 페이지로 돌아가 Create를 클릭합니다.

4. 이름을 Five9로 지정하고, MCP server URL을 https://<your-worker>.workers.dev/mcp로 설정한 다음 OAuth 인증을 선택합니다.

5. 신뢰 프롬프트를 확인하고 저장합니다. ChatGPT가 이 서버의 인증 페이지를 엽니다 — MCP_AUTH_TOKEN을 붙여넣고 Authorize를 클릭하세요.

6. 새 채팅에서 ＋ / tools 메뉴를 열고 Five9 커넥터를 활성화합니다(Developer mode 커넥터는 대화별로 활성화됩니다). ChatGPT가 각 도구 호출을 확인하도록 요청합니다 — 다이얼러를 시작할 수 있는 작업이라면 합리적입니다. 😄

Claude Code 연결

claude mcp add --transport http five9 https://<your-worker>.workers.dev/mcp \
  --header "Authorization: Bearer <your MCP_AUTH_TOKEN>"

액세스 키 원본을 bearer 토큰으로 바로 사용할 수 있습니다 — OAuth 절차가 필요 없습니다. 확인하려면 Claude Code 안에서 /mcp를 실행하세요.

기타 MCP 클라이언트

MCP streamable HTTP를 지원하는 모든 클라이언트에서 작동합니다 — OAuth 흐름을 완료하거나 액세스 키를 bearer 토큰으로 보내세요:

curl -X POST https://<your-worker>.workers.dev/mcp \
  -H "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_connection","arguments":{}}}'

src/oauth.js는 단일 운영자(single-operator) 배포를 위해 설계된 최소한의 OAuth 2.1 인증 서버(메타데이터 검색, 동적 클라이언트 등록, PKCE S256, 갱신 토큰)를 구현합니다:

• 동의 화면의 "login"은 서버의 액세스 키(MCP_AUTH_TOKEN)입니다.

• 모든 것이 무상태(stateless)입니다 — 클라이언트 ID, 인증 코드, 토큰은 MCP_AUTH_TOKEN을 키로 하는 HMAC-SHA256 서명 blob입니다. KV도, Durable Objects도 없습니다.

• 두 인증 경로가 동시에 작동합니다: OAuth로 발급된 토큰 그리고 bearer 자격 증명으로서의 원시 키.

• 비밀을 교체하면 모든 것이 한 번에 취소됩니다: npx wrangler secret put MCP_AUTH_TOKEN.

🧰 도구 상자

77개의 도구. 🟢 = 읽기(항상 안전) · ✏️ = 쓰기(도메인에 변경을 가합니다 — 서버가 AI에게 먼저 사용자 확인을 받도록 안내합니다)

69개의 SOAP 도구(사용자 이름/비밀번호) + 8개의 OAuth New Platform REST 도구(Consumer Key/Secret — OAuth New Platform APIs 참조).

핵심 기능: 콜 흐름을 한 문단으로 설명하면 AI가 설계하고, 채팅에서 Mermaid 다이어그램을 보여주며, 작동하는 IVR 스크립트를 배포합니다. 모델은 Five9의 IVR XML을 즉흥적으로 만들지 않습니다. 제약된 JSON 흐름 스펙(play / menu / business-hours / skill transfer / voicemail / hangup)을 채우면, 그래프 검증기가 모든 분기와 참조를 확인하고, 결정론적 코드가 디자이너 형식의 XML(모듈 연결, 프롬프트 인코딩, 필드 순서는 모두 실제 내보낸 스크립트에서 파생)을 생성합니다.

권장 흐름: validate → render(사람에게 보여주세요!) → generate prompts → build → 인바운드 캠페인에 연결. generate_prompt_audio는 추가 설정 없이 Cloudflare Workers AI에서 실행됩니다: 외부 TTS 계정도, API 키도 필요 없고, 프롬프트당 1센트 미만으로 이미 배포한 Cloudflare 계정에 청구됩니다. ElevenLabs/OpenAI도 해당 키 시크릿을 설정하면 사용할 수 있으며, {tts} 프롬프트(Five9 내장 로봇 음성)는 아무것도 필요하지 않습니다.

이 도구들은 위의 도구들이 사용하는 SOAP API가 아닌 Five9의 최신 OAuth 2.0 "New Platform" REST API를 사용합니다. 이를 위해서는 API Access Control 자격 증명(Consumer Key/Secret)이 필요하며, SOAP 사용자 이름/비밀번호가 아닙니다 — OAuth New Platform APIs 참조.

🔐 OAuth New Platform APIs

SOAP 도구와 함께, 서버는 Five9의 최신 OAuth 2.0 New Platform REST API를 호출할 수 있습니다 (예: Circles, interactions, prompts, domain metadata). 이들은 SOAP 사용자 이름/비밀번호와 다른 자격 증명을 사용합니다:

• API Access Control Consumer Key 및 Consumer Secret — Five9 Admin Console → API Access Control에서 생성됩니다(Controlled-Availability 기능). 생성하려면 security → applications → Create applications 권한이 필요하며, 계정이 Five9 Identity Service로 마이그레이션되어야 합니다(레거시 API/Agent/Supervisor 역할이 있는 사용자는 해당 역할이 제거될 때까지 마이그레이션에서 제외됩니다).

• 이를 env/secret 변수로 구성하세요(SOAP 자격 증명과 모두 별도로):

FIVE9_CONSUMER_KEY=...           # "All APIs access" family credential (default)
FIVE9_CONSUMER_SECRET=...
FIVE9_DOMAIN_ID=131109           # your Admin Console domain id
FIVE9_REST_REGION=US             # US | US-ALPHA | CA | EU | IN | UK
# or pin the base URL directly: FIVE9_REST_BASE_URL=https://api.prod.us.five9.net

# Optional second credential for the "Data Tables access" family (its own key):
FIVE9_DT_CONSUMER_KEY=...
FIVE9_DT_CONSUMER_SECRET=...

그런 다음 rest_check_connection을 실행하여 토큰 흐름을 확인하세요. 각 자격 증명이 접근할 수 있는 범위는 해당 API 패밀리 + 범위(scopes) 에 의해 결정됩니다 — all-apis-access는 말 그대로 모든 서비스를 부여하지 않으며, 쓰기 액세스는 서비스별로 다릅니다.

여러 자격 증명 / 패밀리. 각 API Access Control 자격 증명은 하나의 패밀리(Apigee API Product에 매핑됨)에 속하며, 해당 패밀리가 키가 호출할 수 있는 서비스를 결정합니다. 서버는 명명된 자격 증명을 지원합니다: default(FIVE9_CONSUMER_KEY/SECRET에서) 및 data-tables(FIVE9_DT_CONSUMER_KEY/SECRET에서). Data Tables 도구는 자동으로 data-tables 자격 증명을 사용합니다; rest_call 및 rest_check_connection은 credential 인수를 받아 하나를 선택할 수 있습니다.

참고: Five9 시작 가이드 문서에는 토큰 엔드포인트가 /v1/auth/token으로 나와 있지만, 실제 엔드포인트는 **/oauth2/v1/token**입니다(이 클라이언트가 사용하는 것).

🎨 운영자 컨텍스트 사용자 지정

src/about.js에는 MCP instructions 필드와 about 도구를 통해 연결된 AI에 제공되는 텍스트가 들어 있습니다: 서버를 운영하는 사람, 서버가 존재하는 이유, AI가 어떻게 행동해야 하는지(예: "쓰기 작업 전에 확인"). 자신의 배포를 설명하도록 편집하세요 — 원래 운영자의 컨텍스트를 예시로 포함하고 있습니다.

🏗️ 아키텍처

빌드 단계도, 의존성도 없습니다 — src/의 순수 JS 모듈:

src/
├── index.js   # router, CORS, MCP JSON-RPC handler, /setup endpoint
├── five9.js   # SOAP client: envelope builder, ~60-line XML parser, one method per Five9 op
├── tools.js   # MCP tool definitions (JSON Schema) + dispatch
├── oauth.js   # stateless OAuth 2.1 server (single-operator model)
├── config.js  # config resolution: Wrangler secrets > KV (setup wizard)
├── ui.js      # landing page, setup wizard, interactive console
└── about.js   # operator context — edit this for your deployment

요청은 무상태(stateless)입니다: 모든 MCP 호출은 HTTP Basic 인증으로 새 Five9 SOAP 교환을 엽니다. Statistics API는 추가로 setSessionParameters 호출이 필요하며, get_realtime_stats가 호출 시마다 이를 수행합니다.

• Five9의 엔드포인트는 JAXB로 생성되며 WSDL을 기준으로 자식 요소 순서를 검증합니다. 이 서버를 확장하려면 WSDL(https://api.five9.com/wsadmin/v13/AdminWebService?wsdl, HTTP Basic 인증)을 가져와 <xs:sequence> 순서를 정확히 일치시키세요 — basicImportSettings 같은 기본 유형도 포함하며, 해당 요소들은 확장의 요소들 앞에 옵니다.

• addToListCsv는 WSDL이 대부분 minOccurs="0"으로 표시함에도 cleanListBeforeUpdate, crmAddMode, crmUpdateMode, listAddMode를 요구합니다.

• 목록/CRM 가져오기는 비동기적입니다: 호출은 즉시 가져오기 식별자를 반환하며, 결과를 얻으려면 get_import_result를 폴링하세요.

• 연락처 레코드 값은 래핑되어 반환됩니다(<values><data>…</data></values>); 여러 응답은 1개 요소 배열을 기대하는 곳에서 단일 객체를 반환합니다. five9.js의 toArray()가 이를 정규화합니다.

• 보고서 시간 조건 순서는 <end>가 <start> 앞에 옵니다 (JAXB 알파벳순 정렬).

• IVR xmlDefinition은 비주얼 디자이너의 저장 형식입니다: 모듈은 GUID(ascendants / singleDescendant / branches)로 연결되고, 인라인 TTS 텍스트는 gzip+base64 speakElement 문서로 저장되며, 영업 시간 확인은 __DAY__(SUN=1..SAT=7) 및 __TIME__(자정 이후 분) 시스템 변수를 비교합니다. ivr.js가 이 모두를 캡슐화합니다.

• getPrompts는 프롬프트 id를 반환하지 않습니다 (이름 + 유형만). IVR XML 내부의 파일 프롬프트 참조는 id 0 + 프롬프트 이름으로 허용되며 서버 측에서 정규화됩니다; 푸시된 스크립트는 서버가 부여한 domainId가 추가된 채 왕복합니다.

🛡️ 보안

• Five9 자격 증명은 Cloudflare 계정에만 저장됩니다 — Worker 비밀로, 또는 (마법사 경로) Workers KV 네임스페이스에 저장 시 암호화되어 보관됩니다. 어떤 도구도 이를 반환하지 않으며, Wrangler 비밀이 항상 KV를 덮어씁니다.

• 설정 마법사는 새로 배포되어 아직 구성되지 않은 서버에서만 열립니다 — 배포 직후 실행하세요. 일단 구성되면 모든 변경에는 현재 액세스 키가 필요하며, env로 관리되는 서버는 마법사 변경을 완전히 거부합니다.

• 항상 설정을 완료하세요 (또는 MCP_AUTH_TOKEN을 설정하세요). 액세스 키 없이 구성되지 않은 서버는 열린 상태로 실행됩니다 — URL을 찾은 사람은 누구나 여러분의 컨택 센터를 마음대로 조종할 수 있습니다.

• 쓰기 도구(위 ✏️)는 도메인을 변경합니다. Five9 API 사용자 역할을 AI가 실제로 수행하길 원하는 범위로 한정하세요 — Five9 권한이 실제 보안 경계입니다.

• manage_dnc remove와 delete_list는 특히 주의가 필요합니다; about 지침은 AI에게 사용 전에 확인하도록 안내합니다.

• 콘솔은 액세스 키를 브라우저의 localStorage에만 저장하며, 호출은 동일 출처(same-origin)로 여러분 자신의 Worker에 전달됩니다.

💻 개발

npm run dev      # wrangler dev on http://localhost:8787
npm run deploy   # wrangler deploy

로컬 비밀을 .dev.vars에 넣으세요 (gitignore 처리됨):

FIVE9_USERNAME=apiuser@yourdomain
FIVE9_PASSWORD=...
MCP_AUTH_TOKEN=dev-local-token

# Optional — external AI voice providers for generate_prompt_audio.
# The default (Workers AI / Deepgram Aura) needs no key at all.
ELEVENLABS_API_KEY=...
OPENAI_API_KEY=...

# Optional — OAuth New Platform REST tools (separate credential; see below)
FIVE9_CONSUMER_KEY=...
FIVE9_CONSUMER_SECRET=...
FIVE9_DOMAIN_ID=131109
FIVE9_REST_REGION=US
FIVE9_DT_CONSUMER_KEY=...        # optional: "Data Tables access" family
FIVE9_DT_CONSUMER_SECRET=...

그런 다음 http://localhost:8787/console을 열고 dev-local-token을 붙여넣은 후 도메인에 대해 도구를 실행하세요 — 또는 위의 curl 스니펫으로 CLI에서 스모크 테스트를 하세요.

🤝 기여

PR 환영합니다! Five9 Config API에는 ~180개의 작업이 있으며, 이 서버는 가장 유용한 69개를 래핑합니다 — five9.js + tools.js의 패턴은 확장하기 쉽습니다(먼저 SOAP 참고 사항을 읽으면 WSDL과 싸우지 않아도 됩니다). 제로 의존성 제약을 지켜 주세요.

📄 라이선스

MIT · 제작: Ryan Shatzkamer