Vapi client MCP

클라이언트 수준 Vapi 인바운드 응답 어시스턴트를 프로비저닝하기 위한 로컬 stdio MCP 서버입니다. 더 작은 호스팅 Vapi MCP 도구 세트 대신 Vapi REST API를 래핑합니다.

첫 번째 템플릿은 즉시 응답하고, 자신이 AI임을 밝히며, 발신자의 이름, 콜백 번호, 사유, 콜백 시간대를 캡처한 후, 가능한 전환(transfer) 또는 명확히 설명된 콜백을 제공합니다. 통화 종료 데이터는 공개 웹훅으로 보내거나 이후 CRM 처리를 위해 Vapi에 남길 수 있습니다.

구현된 기능

클라이언트 레코드는 clients/<slug>.json에 저장됩니다. 여기에는 Vapi 리소스 ID와 비밀번호가 아닌 비즈니스 구성이 포함되며, Vapi 키나 공급자 자격 증명은 절대 포함되지 않습니다. 비즈니스 메타데이터 자체를 커밋해도 괜찮다면 이러한 JSON 파일은 config-as-code에 적합합니다.

Related MCP server: RetellAI MCP Server

설치 및 실행

Node.js 20 이상이 필요합니다.

cd /home/blaine/projects/vapi-mcp
npm install
npm run check
npm run build
export VAPI_API_KEY="your private server-side Vapi key"
npm start

서버는 stdio를 통해 MCP를 사용하므로 표준 출력은 프로토콜 메시지용으로 예약되어 있습니다. 로그는 표준 오류로 출력됩니다.

MCP 호스트의 경우 examples/mcp-client.json을 복사하고 절대 경로를 교체한 다음, 실제 키는 호스트의 비공개 구성 또는 비밀 관리자에만 넣으세요. 체크인된 예제와 .env.example에는 플레이스홀더만 포함되어 있습니다. 이 프로젝트는 .env 파일을 자동으로 로드하지 않습니다.

첫 번째 클라이언트 워크플로우

다음 순서로 도구를 호출하세요:

1. provision_client

2. set_structured_outputs

3. attach_phone

4. attach_tools - 전환, 콜백, 캘린더 또는 CRM 작업용

5. smoke_test_call

6. list_client_status

provision_client 인수 예시:

{
  "clientSlug": "acme-hvac",
  "businessName": "Acme HVAC",
  "trade": "HVAC",
  "timezone": "America/New_York",
  "businessHours": "Monday-Friday 08:00-17:00; closed federal holidays",
  "transferNumber": "+12125550123",
  "crm": "GoHighLevel",
  "webhookUrl": "https://example.com/webhooks/vapi/end-of-call"
}

outputDefinitions가 없으면 set_structured_outputs는 templates/inbound-answering.json에서 스키마를 설치합니다. 다음을 추출합니다:

• callerName

• callbackNumber

• reason

• callbackWindow

• transferOutcome

• complete

기존 번호 바인딩:

{
  "clientSlug": "acme-hvac",
  "phoneNumberId": "00000000-0000-4000-8000-000000000000"
}

또는 공급자별 POST /phone-number 본문을 phoneConfiguration으로 전달하세요. 서버는 제공된 assistantId를 클라이언트의 어시스턴트 ID로 재정의합니다. 원시 Twilio, Telnyx, Vonage 또는 SIP 비밀보다 Vapi 자격 증명 ID를 선호하세요. 일시적인 MCP 인수는 클라이언트 레코드에 기록되지 않습니다.

attach_tools는 완전한 Vapi POST /tool 정의, 기존 도구 UUID 또는 둘 다를 허용합니다. 이는 더 좁은 로컬 스키마를 만들지 않고 Vapi의 공급자별 도구 유니온을 의도적으로 보존합니다. 도구 ID가 어시스턴트에 연결되기 전에 성공적인 Vapi 도구 응답이 필요합니다.

스모크 경로

smoke_test_call은 실제 발신 전화를 생성하며 Vapi 및 통신사 요금이 발생할 수 있습니다. confirmBillableCall이 정확히 true인 경우에만 실행됩니다.

{
  "clientSlug": "acme-hvac",
  "customerNumber": "+12125550999",
  "waitSeconds": 45,
  "confirmBillableCall": true
}

waitSeconds: 0에서 도구는 대기 중인 통화를 즉시 반환합니다. 1~55초에서는 GET /call/:id를 폴링하고 현재 상태, 종료 사유, 대화 기록, 구조화된 데이터를 사용 가능할 때 반환합니다. 통화 권한이 있는 번호만 테스트하고 해당 통화, 녹음 동의, 개인정보 보호 규정을 준수하세요.

템플릿 동작 및 제한 사항

템플릿은 어시스턴트 우선 메시지를 사용하여 즉시 공개합니다. 프롬프트는 음성 의도 라우팅을 사용하며 도구 확인 없이 전환, 예약, 콜백 또는 CRM 쓰기가 성공했다고 주장하지 말라고 모델에 지시합니다. 영업/휴무 상태가 불확실한 경우 추측하지 않고 콜백을 캡처합니다.

포함된 영업 시간은 프롬프트 컨텍스트일 뿐 결정적 휴일/캘린더 엔진이 아닙니다. 실제 전환 및 콜백 실행에는 연결된 Vapi 도구가 필요합니다. 웹훅은 공개되어야 하며 Vapi end-of-call-report 페이로드를 수락할 수 있어야 합니다. 규제 대상 비즈니스의 경우 프로덕션 전에 필수 녹음 동의, 보존, 전문 조언 통제를 추가하세요.

검증

npm run check

집중 테스트는 8개의 MCP 도구를 모두 열거하고, 템플릿 계약을 검사하며, 모의 Vapi 클라이언트에 대해 REST 워크플로우를 실행하고, 베어러 키 삭제를 검증합니다. 이 저장소에는 개인 키, 프로비저닝된 번호 또는 동의된 대상이 포함되어 있지 않으므로 실제 Vapi 통화를 하지 않습니다.

출처

구현 계약은 assistants, phone numbers, custom tools, structured outputs, calls, server events에 대한 Vapi의 현재 공식 문서를 따릅니다.