Claude가 나를 대신해 Cognigy.AI 에이전트를 관리할 수 있도록 132개의 도구를 갖춘 MCP 서버를 구축했습니다

저는 Deloitte에서 근무하는 동안 Cognigy.AI를 사용하여 엔터프라이즈 음성 봇, 다국어 플로우(flows), NLU 학습 등 대화형 AI 에이전트를 구축하는 데 꽤 많은 시간을 보냈습니다. 이는 매우 강력한 플랫폼입니다. 하지만 동시에 클릭해야 할 작업이 정말 많습니다. 플로우를 생성하고, 노드 에디터(node editor)를 열고, 노드를 구성하고, 인텐트(intents)를 학습시키고, 스냅샷(snapshot)을 생성하고, 다음 환경으로 승격(promote)시키는 과정 말이죠... 이제는 코딩 어시스턴트가 전체 애플리케이션을 작성할 수 있는 세상에 살고 있지만, 정작 이 작업들은 전혀 건드릴 수 없었습니다.

그래서 제가 해결했습니다. **cognigy-ai-mcp-management-server**는 Claude, Claude Code, Cursor와 같은 AI 어시스턴트에게 Cognigy.AI 관리 API에 대한 프로그래밍 방식의 접근 권한을 제공하는 로컬 MCP (Model Context Protocol) 서버입니다. 132개의 도구, TypeScript 기반, MIT 라이선스이며, npm에서 사용할 수 있습니다.

이제 UI를 일일이 클릭하는 대신, 어시스턴트에게 다음과 같이 말할 수 있습니다:

"이 예시 문장들을 사용하여 주문 취소를 위한 새로운 인텐트를 생성하고, NLU를 재학습시켜줘"
"회귀 테스트(regression test) 플레이북을 실행하고 무엇이 깨졌는지 요약해줘"
"현재 스냅샷을 운영 환경(production)과 비교(diff)하여 무엇이 변경되었는지 알려줘"
"이 폐기된 연결(deprecated connection)을 사용하는 모든 플로우를 찾아줘"

포함된 기능

132개의 도구는 기본적으로 관리 영역 전체를 아우릅니다: 플로우(flows) 및 노드(nodes) (전체 CRUD 및 검색, AI 출력 생성 포함), 인텐트(intents) 및 NLU 학습, 플레이북(playbooks) 및 회귀 테스트(regression testing), 스냅샷(snapshots) 및 패키지(packages) (생성, 비교, 환경 간 승격), Knowledge AI / RAG 저장소 (이 기능에만 21개의 도구), LLM 제공자 설정, 연결(connections), 확장(extensions), GDPR 내보내기가 가능한 연락처 프로필(contact profiles), 분석(analytics) 및 감사 로그(audit logs). 전체 목록은 TOOLS.md에서 확인할 수 있습니다.

코드 리뷰에서 방어할 설계 결정 사항

프로덕션 대화형 AI 에이전트를 _변형(mutate)_시킬 수 있는 MCP 서버를 구축하는 것은 읽기 전용 통합과는 다르게 안전성에 대해 생각하도록 강제합니다. 제가 내린 몇 가지 선택은 다음과 같습니다:

1. 모든 변형 도구에 기본적으로 dryRun: true 적용. 프로덕션 에이전트에 쓰기 접근 권한을 가진 LLM은 예초기와 같습니다. 무언가를 생성, 업데이트 또는 삭제하는 모든 도구는 기본적으로 건조 실행(dry run)으로 설정됩니다. 어시스턴트는 무엇이 일어날지 정확히 확인하고, 실행하려면 플래그를 명시적으로 전환해야 합니다. 파괴적인 경로는 단순한 환각된 도구 호출만으로는 이루어질 수 없고 의도가 필요합니다.

2. 시크릿은 모델에 절대 전달되지 않음. API 키는 환경 변수와 메모리에만 존재하며, Cognigy API에서 돌아오는 연결 시크릿은 LLM이 보기 전에 자동으로 마스킹됩니다. 모델 컨텍스트에는 결코 자격 증명(credentials)이 포함되어서는 안 됩니다. 이는 협상 불가능한 사항입니다.

3. 비동기 작업 인지 도구화 (Async-aware tooling). NLU 학습 및 스냅샷 작업은 Cognigy 측에서 장시간 실행되는 작업입니다. 이 도구들은 단순히 작업 ID를 반환하고 LLM이 추측하도록 내버려 두는 대신, 작업 완료 시까지 상태를 폴링(poll)합니다. 이는 다단계 에이전트 워크플로우가 조용히 동기화되지 않는 것을 방지해 줍니다.

4. 모든 입력에 Zod 검증 적용. LLM은 대부분 정확한 도구 인수를 생성합니다. 여기서 '대부분'이라는 단어가 많은 노력을 기울이고 있습니다. 모든 도구는 API로 전송되기 전에 Zod 스키마를 사용하여 입력을 검증합니다.

5. 번들링 대신 피어 의존성(Peer dependency) 사용. Cognigy의 공식 REST 클라이언트는 독점 라이선스(proprietary license) 하에 게시되었기 때문에, 이 서버는 이를 번들링하는 대신 피어 의존성으로 선언합니다. 사용자가 직접 설치하고 Cognigy의 약관을 직접 수락해야 합니다. 저의 MIT 라이선스는 오직 제 코드만을 다룹니다. 라이선스 위생 관리는 재미없다가 그렇지 않을 때까지 그렇습니다.

Mock-first 개발

이것을 만지기 위해 Cognigy 계정이 필요하지 않습니다. 이 저장소는 OpenAPI 스펙에서 생성된 Prism 모의 서버와 함께 제공됩니다:

# Terminal 1
npm run mock

...

OpenAPI 스펙으로부터 TypeScript 타입도 생성되므로 (npm run gen:types), Cognigy가 API를 업데이트할 때 타입을 재생성하면 누군가의 프로덕션 테넌트(production tenant)에서 런타임(runtime)에 오류가 발생하는 대신 컴파일 타임(compile time)에 오류를 확인할 수 있습니다.

시작하기

npm install @cognigy/rest-api-client   # 공식 Cognigy SDK, 해당 라이선스 적용
npm install -g cognigy-ai-mcp-management-server

그 다음 MCP 클라이언트가 이를 가리키도록 설정하세요. Claude Code의 경우, .mcp.json에 다음을 추가합니다:

{
  "mcpServers": {
    "cognigy": {
...

Cognigy 무료 체험 계정, SaaS, 또는 온프레미스(on-prem) 환경에서 모두 작동합니다. Claude Desktop 및 Cursor를 위한 설정은 README에 있습니다.

솔직한 각주

프로젝트 중간에 NiCE(Cognigy의 모회사)에서 공식 MCP 서버를 출시했다는 사실을 알게 되었습니다. 제 프로젝트를 포기할까 고민했냐고요? 한 시간 정도는 그랬습니다. 하지만 저는 계속 진행했습니다. 왜냐하면 (a) 모든 API 범위를 매핑하면서 Management API 인터페이스에 대해 엄청난 양을 배우고 있었고, (b) 독립적이며 MIT 라이선스를 따르고, 모의 테스트(mock-testable)가 가능하며, 기본적으로 dryRun(실행 시뮬레이션) 세맨틱을 갖춘 구현체는 공식 제품과는 다른 결과물이기 때문입니다. 만약 공식 서버가 귀하의 요구사항에 더 잘 맞는다면 — 그것을 사용하세요! 이 프로젝트는 존재하며, 공개되어 있고, 대규모 엔터프라이즈 API를 LLM에 안전한 도구로 래핑(wrap)하는 방법을 정확히 보여줍니다. 그 사실 하나만으로도 배포할 가치가 충분했습니다.

(표준 면책 조항: 이 프로젝트는 독립적인 프로젝트이며, Cognigy 또는 NiCE와 제휴하거나 그들로부터 승인받지 않았습니다. 귀하의 자체 Cognigy 계정과 API 키가 필요합니다.)

시도해 보세요

개발자, 솔루션 아키텍트(solution architect), 또는 SI 파트너로서 Cognigy.AI를 기반으로 구축하고 계신다면, 어떤 워크플로우를 가장 먼저 자동화하고 싶은지 진심으로 듣고 싶습니다. 그리고 만약 다른 엔터프라이즈 플랫폼을 위한 MCP 서버를 구축하고 계신다면, 여기에 사용된 dryRun + 데이터 마스킹(redaction) + 비동기 폴링(async-polling) 패턴은 이식 가능하므로 — 마음껏 가져다 쓰셔도 좋습니다.