WorkForceAI MCP Server

이것은 "내부 봇의 도구 상자"입니다. 채팅/음성 봇이 메인 앱이 사용하는 것과 동일한 백엔드를 호출하여 WorkForceAI 플랫폼(에이전트, 캠페인, 전화번호, 통화 기록, 통계)의 항목을 조회하고 업데이트할 수 있게 해주는 소규모 독립 서버입니다.

이 서버는 healthai-frontend 저장소와 완전히 분리되어 있습니다 — 여기의 어떤 것도 그 저장소로 푸시되지 않습니다. MCP(Model Context Protocol)라는 표준 프로토콜을 사용하며, 이는 AI(Claude, ElevenLabs 에이전트 등)가 "내가 할 수 있는 일들"을 발견하고 대화 중에 호출할 수 있게 해줍니다.

MCP 내부 구조를 이해할 필요는 없습니다 — 아래 단계만 따르면 됩니다.

지금 할 수 있는 것

읽기 전용(안전한 조회 도구):

• list_voice_agents — CallFlow 음성 에이전트 목록 조회

• list_campaigns — 캠페인 목록 조회 또는 특정 캠페인의 전체 세부 정보 확인

• list_phone_numbers — 프로비저닝된 Twilio 번호 목록 조회

• get_call_logs — 최근 통화 기록/대화 내용 조회

• get_dashboard_stats — 통화량/사용량 통계 조회

• get_current_account — 봇이 로그인한 계정 확인

액션 도구 하나(실제 데이터 변경):

• update_campaign — 캠페인의 시스템 프롬프트, 인사말, 이름, 목표 등을 업데이트합니다. campaignId가 필요하며, 전달한 필드만 변경됩니다.

이 모든 것은 .env에 넣은 계정의 로그인 범위로 제한됩니다 — 봇은 해당 계정이 플랫폼에서 볼 수 있는 것만 정확히 볼 수 있으며, 그 이상은 볼 수 없습니다.

Related MCP server: @davoxi/mcp-server

최초 설정

1. 의존성 설치

이 폴더(E:\aiconnecthub\workforceai-mcp)에서 터미널을 열고 다음을 실행하세요:

npm install

(이 머신에는 Node.js가 이미 설치되어 있습니다 — 추가로 설치할 것은 없습니다.)

2. .env 파일 설정

.env 파일이 이미 이곳에 있으며 로그인 정보가 입력되어 있고 실제 WorkForceAI 백엔드(https://workforceai.zapto.org)를 가리키고 있습니다. 봇이 로그인할 계정을 변경해야 한다면 .env를 직접 편집하세요:

BACKEND_BASE_URL=https://workforceai.zapto.org
BOT_ACCOUNT_EMAIL=your-login-email
BOT_ACCOUNT_PASSWORD=your-login-password
MCP_PORT=8787

이 파일을 공유하거나 어디에도 커밋하지 마세요 — 실제 비밀번호가 들어 있습니다. .gitignore에 이미 제외되어 있으므로, 나중에 이 폴더를 git 저장소로 만들어도 .env가 실수로 커밋되지 않습니다.

3. 서버 시작

npm start

다음과 같은 화면이 보일 것입니다:

workforceai-mcp listening on http://localhost:8787
  MCP endpoint: http://localhost:8787/mcp
  Health check: http://localhost:8787/health

테스트하거나 봇을 사용하는 동안 이 서버를 별도의 터미널 창에서 계속 실행해 두세요. 중지하려면 Ctrl+C를 누르세요.

4. 작동 확인

빠른 확인(추가 도구 불필요): 브라우저에서 http://localhost:8787/health를 열면 — {"ok":true}가 표시되어야 합니다.

전체 확인(실제 도구를 보고 하나 시도): 공식 MCP Inspector를 사용하세요 — MCP 서버를 수동으로 조작하기 위한 브라우저 기반 도구입니다. 두 번째 터미널에서(첫 번째 터미널에는 서버를 계속 실행해 두세요):

npx @modelcontextprotocol/inspector

그러면 브라우저 탭이 열립니다. 다음을 수행하세요:

1. Transport Type을 Streamable HTTP로 설정

2. URL을 http://localhost:8787/mcp로 설정

3. Connect 클릭

4. Tools 탭으로 이동하여 list_voice_agents 같은 도구를 클릭하고 Run을 클릭하세요 — 실제 에이전트가 JSON으로 반환되는 것을 볼 수 있습니다.

이것이 작동하면 서버는 완전히 검증된 것이며 봇에 연결할 준비가 된 것입니다.

인증 작동 방식 (예상치 못한 일을 피하기 위해)

현재 백엔드에는 별도의 "봇 API 키" 시스템이 없습니다 — 봇은 웹사이트의 로그인 폼과 똑같이 일반 이메일/비밀번호로 로그인하고, 모든 요청에 첨부하는 JWT 토큰을 받습니다. 이 토큰을 메모리(디스크가 아닌)에 보관하며, 토큰이 만료되거나 요청이 인증되지 않음으로 반환되면 자동으로 다시 로그인합니다. 이는 프론트엔드 앱의 utils/apiClient.js가 하는 방식과 동일하지만, 브라우저가 없다는 점만 다릅니다.

이 때문에 봇은 해당 로그인이 볼 수 있는 것만 보고/변경할 수 있습니다 — 자신의 에이전트, 캠페인, 번호, 통화 기록만 가능합니다. 다른 사용자의 계정은 볼 수 없고 건드릴 수도 없습니다.

프로젝트 구조

workforceai-mcp/
├── .env              ← your real credentials (gitignored, never share)
├── .env.example       ← template, safe to share
├── src/
│   ├── config.js      ← reads .env
│   ├── backendClient.js ← logs in, attaches auth token, retries on expiry
│   ├── tools.js        ← the actual tool definitions (add new ones here)
│   └── server.js       ← the MCP server itself (Express + Streamable HTTP)
└── README.md          ← this file

나중에 새 도구를 추가하려면: src/tools.js의 tools 배열에 기존 패턴(이름, 설명, 입력 필드, 백엔드에 대해 http.get/post/put을 호출하는 핸들러)을 따라 항목을 추가하고, 서버를 재시작하면 끝입니다.

아직 완료되지 않은 것 (다음 단계)

이 서버는 현재 자신의 머신(localhost)에서만 실행됩니다 — 인터넷에서 접근할 수 없습니다. ElevenLabs 음성 에이전트에 연결하려면 ElevenLabs의 서버가 인터넷을 통해 이 MCP 엔드포인트에 접근할 수 있어야 하며, 이는 다음 중 하나를 의미합니다:

• 터널(예: ngrok)을 통해 임시로 노출하거나,

• 계속 실행되는 곳(소규모 상시 가동 서버/VPS/호스팅 서비스)에 배포

그 부분과 실제 ElevenLabs 에이전트 구성은 의도적으로 별도의 다음 단계입니다 — 이번 빌드의 일부가 아닙니다.