WorkForceAI MCP Server

Dies ist die „Werkzeugkiste des internen Bots“ – ein kleiner eigenständiger Server, der es einem Chat-/Sprachbot ermöglicht, Dinge auf der WorkForceAI-Plattform (Agenten, Kampagnen, Telefonnummern, Anrufprotokolle, Statistiken) nachzuschlagen und zu aktualisieren, indem er dasselbe Backend aufruft, das auch die Haupt-App verwendet.

Er ist völlig getrennt vom healthai-frontend-Repository – nichts davon wird dorthin gepusht. Er spricht ein Standardprotokoll namens MCP (Model Context Protocol), das es einer KI (Claude, ElevenLabs-Agent usw.) ermöglicht, zu entdecken: „Hier sind die Dinge, die ich tun darf“ und sie während eines Gesprächs aufzurufen.

Du musst die MCP-Interna nicht verstehen, um das auszuführen – folge einfach den Schritten unten.

Was er derzeit kann

Nur lesend (sichere, nachschlagende Tools):

• list_voice_agents – listet deine CallFlow-Sprachagenten auf

• list_campaigns – listet Kampagnen auf oder ruft die vollständigen Details einer Kampagne ab

• list_phone_numbers – listet bereitgestellte Twilio-Nummern auf

• get_call_logs – aktuelle Anrufaufzeichnungen/Transkripte

• get_dashboard_stats – Anrufvolumen-/Nutzungsstatistiken

• get_current_account – zeigt, mit welchem Konto der Bot angemeldet ist

Ein Aktions-Tool (ändert echte Daten):

• update_campaign – aktualisiert den System-Prompt, die Begrüßung, den Namen, das Ziel usw. einer Kampagne. Erfordert eine campaignId; nur die übergebenen Felder werden geändert.

All dies ist auf das Konto beschränkt, dessen Anmeldung du in .env eingetragen hast – der Bot sieht genau das, was dieses Konto in der Plattform sehen kann, und nicht mehr.

Related MCP server: @davoxi/mcp-server

Einmalige Einrichtung

1. Abhängigkeiten installieren

Öffne ein Terminal in diesem Ordner (E:\aiconnecthub\workforceai-mcp) und führe aus:

npm install

(Node.js ist auf diesem Rechner bereits installiert – sonst ist nichts weiter zu installieren.)

2. Deine .env-Datei einrichten

Eine .env-Datei existiert hier bereits mit deiner Anmeldung, die auf das echte WorkForceAI-Backend (https://workforceai.zapto.org) zeigt. Falls du jemals ändern musst, mit welchem Konto sich der Bot anmeldet, bearbeite .env direkt:

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

Teile diese Datei niemals und committe sie niemals irgendwo – sie enthält ein echtes Passwort. .gitignore schließt sie bereits aus, sodass .env selbst dann nicht versehentlich committet wird, wenn du diesen Ordner später in ein Git-Repository verwandelst.

3. Server starten

npm start

Du solltest sehen:

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

Lass dies in einem eigenen Terminalfenster laufen, während du testest oder den Bot verwendest. Drücke Ctrl+C, um es zu stoppen.

4. Überprüfen, ob es funktioniert

Schnellprüfung (keine zusätzlichen Tools erforderlich): Öffne http://localhost:8787/health in einem Browser – es sollte {"ok":true} anzeigen.

Vollständige Prüfung (die tatsächlichen Tools sehen und eines ausprobieren): Verwende den offiziellen MCP Inspector – ein browserbasiertes Tool, um manuell an einem MCP-Server herumzutesten. In einem zweiten Terminal (lass den Server im ersten weiterlaufen):

npx @modelcontextprotocol/inspector

Dies öffnet einen Browser-Tab. Darin:

1. Setze Transport Type auf Streamable HTTP

2. Setze URL auf http://localhost:8787/mcp

3. Klicke Connect

4. Gehe zum Tools-Tab, klicke auf ein Tool wie list_voice_agents, klicke Run – du solltest deine echten Agenten als JSON zurückbekommen.

Wenn das funktioniert, ist der Server vollständig verifiziert und bereit, mit einem Bot verbunden zu werden.

So funktioniert die Authentifizierung (damit du nicht überrascht bist)

Es gibt heute kein separates „Bot-API-Schlüssel“-System im Backend – der Bot meldet sich mit einer normalen E-Mail/Passwort an, genau wie das Anmeldeformular der Website, und erhält ein JWT-Token, das er an jede Anfrage anhängt. Er hält dieses Token im Speicher (nicht auf der Festplatte) und meldet sich automatisch erneut an, wenn das Token abläuft oder eine Anfrage mit „nicht autorisiert“ zurückkommt. Dies spiegelt wider, was utils/apiClient.js in der Frontend-App tut, nur ohne Browser.

Aus diesem Grund sieht/ändert der Bot nur das, was diese eine Anmeldung sehen kann – seine eigenen Agenten, Kampagnen, Nummern und Anrufprotokolle. Er kann die Konten anderer Benutzer weder sehen noch berühren.

Projektstruktur

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

Um später ein neues Tool hinzuzufügen: Füge einen Eintrag zum tools-Array in src/tools.js hinzu, dem bestehenden Muster folgend (Name, Beschreibung, Eingabefelder, Handler, der http.get/post/put gegen das Backend aufruft), starte den Server neu, fertig.

Was NOCH NICHT erledigt ist (nächste Phase)

Dieser Server läuft derzeit nur auf deinem eigenen Rechner (localhost) – er ist vom Internet aus nicht erreichbar. Um ihn mit einem ElevenLabs-Sprachagenten zu verbinden, müssen die Server von ElevenLabs diesen MCP-Endpunkt über das Internet erreichen können, was entweder bedeutet:

• ihn vorübergehend über einen Tunnel (z. B. ngrok) bereitzustellen, oder

• ihn irgendwo zu deployen, wo er dauerhaft läuft (ein kleiner Always-on-Server/VPS/Hosting-Dienst)

Das, plus die eigentliche Konfiguration des ElevenLabs-Agenten, ist bewusst ein separater nächster Schritt – nicht Teil dieses Builds.