Vapi client MCP

Ein lokaler stdio-MCP-Server für die Bereitstellung von Vapi-Assistenten für eingehende Anrufe auf Client-Ebene. Er kapselt die Vapi-REST-API und nicht den kleineren gehosteten Vapi-MCP-Toolsatz.

Die erste Vorlage antwortet sofort, identifiziert sich als KI, erfasst den Namen des Anrufers, die Rückrufnummer, den Grund und das Rückruffenster und bietet dann einen verfügbaren Transfer oder einen klar erklärten Rückruf an. End-of-Call-Daten können an einen öffentlichen Webhook gehen oder für die spätere CRM-Bearbeitung in Vapi verbleiben.

Was implementiert ist

Clientdatensätze liegen unter clients/<slug>.json. Sie enthalten Vapi-Ressourcen-IDs und nicht geheime Geschäftskonfiguration, niemals den Vapi-Schlüssel oder Anbieteranmeldedaten. Diese JSON-Dateien eignen sich für Config-as-Code, sofern die Geschäftsmetadaten selbst committet werden dürfen.

Related MCP server: RetellAI MCP Server

Installation und Ausführung

Erfordert Node.js 20 oder neuer.

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

Der Server spricht MCP über stdio, daher ist seine Standardausgabe für Protokollnachrichten reserviert. Logs gehen an die Standardfehlerausgabe.

Kopieren Sie für einen MCP-Host examples/mcp-client.json, ersetzen Sie die absoluten Pfade und legen Sie den echten Schlüssel nur in der privaten Konfiguration oder im Secret-Manager des Hosts ab. Das eingecheckte Beispiel und .env.example enthalten nur Platzhalter. Dieses Projekt lädt .env-Dateien nicht automatisch.

Erster Client-Workflow

Rufen Sie die Tools in dieser Reihenfolge auf:

1. provision_client

2. set_structured_outputs

3. attach_phone

4. attach_tools für Transfer, Rückruf, Kalender- oder CRM-Aktionen

5. smoke_test_call

6. list_client_status

Beispielargumente für 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"
}

Ohne outputDefinitions installiert set_structured_outputs das Schema aus templates/inbound-answering.json. Es extrahiert:

• callerName

• callbackNumber

• reason

• callbackWindow

• transferOutcome

• complete

Binden Sie eine vorhandene Nummer:

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

Oder übergeben Sie einen anbieterspezifischen POST /phone-number-Body als phoneConfiguration. Der Server überschreibt jede übergebene assistantId mit der Assistant-ID des Clients. Bevorzugen Sie Vapi-Anmeldedaten-IDs gegenüber rohen Twilio-, Telnyx-, Vonage- oder SIP-Geheimnissen; transiente MCP-Argumente werden nicht in den Clientdatensatz geschrieben.

attach_tools akzeptiert vollständige Vapi-POST /tool-Definitionen, vorhandene Tool-UUIDs oder beides. Dies bewahrt absichtlich Vapis anbieterspezifische Tool-Unionen, anstatt ein engeres lokales Schema zu erfinden. Eine erfolgreiche Vapi-Tool-Antwort ist erforderlich, bevor seine ID an den Assistant angehängt wird.

Smoke-Pfad

smoke_test_call erstellt einen echten ausgehenden Telefonanruf und kann Vapi- und Carrier-Gebühren verursachen. Es wird nur ausgeführt, wenn confirmBillableCall genau true ist.

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

Bei waitSeconds: 0 gibt das Tool den eingereihten Anruf sofort zurück. Bei 1–55 Sekunden pollt es GET /call/:id und gibt aktuellen Status, Beendigungsgrund, Transkript und strukturierte Daten zurück, sofern verfügbar. Testen Sie nur Nummern, die Sie anrufen dürfen, und befolgen Sie die geltenden Regeln für Anrufe, Aufzeichnungseinwilligung und Datenschutz.

Vorlagenverhalten und Grenzen

Die Vorlage verwendet eine Assistant-First-Nachricht, sodass die Offenlegung sofort erfolgt. Der Prompt verwendet gesprochenes Intent-Routing und weist das Modell an, keinen Transfer, keine Buchung, keinen Rückruf oder keinen CRM-Schreibvorgang als erfolgreich zu bezeichnen, ohne eine Tool-Bestätigung zu haben. Wenn der Öffnungs-/Schließungsstatus ungewiss ist, erfasst es einen Rückruf, anstatt zu raten.

Die enthaltenen Öffnungszeiten sind Prompt-Kontext, keine deterministische Feiertags-/Kalender-Engine. Die tatsächliche Ausführung von Transfer und Rückruf erfordert angehängte Vapi-Tools. Ein Webhook muss öffentlich sein und Vapi-end-of-call-report-Payloads akzeptieren können. Für regulierte Unternehmen fügen Sie vor der Produktion die erforderlichen Kontrollen für Aufzeichnungseinwilligung, Aufbewahrung und professionelle Beratung hinzu.

Verifizierung

npm run check

Die fokussierten Tests zählen alle acht MCP-Tools auf, prüfen den Vorlagenvertrag, üben den REST-Workflow gegen einen Mock-Vapi-Client und verifizieren die Schwärzung des Bearer-Schlüssels. Sie führen keinen echten Vapi-Anruf durch, da in diesem Repository kein privater Schlüssel, keine bereitgestellte Nummer und kein Ziel mit Einwilligung enthalten ist.

Quellen

Die Implementierungsverträge folgen Vapis aktueller offizieller Dokumentation für Assistenten, Telefonnummern, benutzerdefinierte Tools, strukturierte Ausgaben, Anrufe und Server-Events.