WorkForceAI MCP Server

This is the "internal bot's toolbox" — a small standalone server that lets a chat/voice bot look up and update things on the WorkForceAI platform (agents, campaigns, phone numbers, call logs, stats) by calling the same backend the main app uses.

It is completely separate from the healthai-frontend repo — nothing here gets pushed there. It speaks a standard protocol called MCP (Model Context Protocol), which is what lets an AI (Claude, ElevenLabs' agent, etc.) discover "here are the things I'm allowed to do" and call them during a conversation.

You do not need to understand MCP internals to run this — just follow the steps below.

---

What it can do right now

Read-only (safe, look-things-up tools):

• list_voice_agents — list your CallFlow voice agents
• list_campaigns — list campaigns, or get one campaign's full details
• list_phone_numbers — list provisioned Twilio numbers
• get_call_logs — recent call records/transcripts
• get_dashboard_stats — call volume/usage stats
• get_current_account — which account the bot is logged in as

One action tool (changes real data):

• update_campaign — update a campaign's system prompt, greeting, name, objective, etc. Requires a campaignId; only the fields you pass get changed.

All of this is scoped to whichever account's login you put in .env — the bot sees exactly what that account can see in the platform, nothing more.

---

One-time setup

1. Install dependencies

Open a terminal in this folder (E:\aiconnecthub\workforceai-mcp) and run:

npm install

(Node.js is already installed on this machine — nothing else to install there.)

2. Set up your .env file

A .env file already exists here with your login filled in, pointing at the real WorkForceAI backend (https://workforceai.zapto.org). If you ever need to change which account the bot logs in as, edit .env directly:

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

Never share this file or commit it anywhere — it has a real password in it. .gitignore already excludes it, so even if you turn this folder into a git repo later, .env won't get committed by accident.

3. Start the server

npm start

You should see:

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

Leave this running in its own terminal window while you're testing or using the bot. Press Ctrl+C to stop it.

4. Verify it's working

Quick check (no extra tools needed): open http://localhost:8787/health in a browser — it should show {"ok":true}.

Full check (see the actual tools and try one): use the official MCP Inspector — a browser-based tool for poking at an MCP server by hand. In a second terminal (leave the server running in the first one):

npx @modelcontextprotocol/inspector

This opens a browser tab. In it:

1. Set Transport Type to Streamable HTTP
2. Set URL to http://localhost:8787/mcp
3. Click Connect
4. Go to the Tools tab, click a tool like list_voice_agents, click Run — you should see your real agents come back as JSON.

If that works, the server is fully verified and ready to be connected to a bot.

---

How authentication works (so you're not surprised)

There's no separate "bot API key" system on the backend today — the bot logs in with a normal email/password, exactly like the website's login form does, and gets back a JWT token it attaches to every request. It keeps that token in memory (not on disk) and automatically logs in again if the token expires or a request comes back unauthorized. This mirrors what utils/apiClient.js does in the frontend app, just without a browser.

Because of this, the bot only ever sees/changes what that one login can see — its own agents, campaigns, numbers, and call logs. It cannot see or touch other users' accounts.

---

Project layout

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

To add a new tool later: add an entry to the tools array in src/tools.js following the existing pattern (name, description, input fields, handler that calls http.get/post/put against the backend), restart the server, done.

---

What's NOT done yet (next phase)

This server currently only runs on your own machine (localhost) — it isn't reachable from the internet. To wire it up to an ElevenLabs voice agent, ElevenLabs' servers need to be able to reach this MCP endpoint over the internet, which means either:

• exposing it temporarily via a tunnel (e.g. ngrok), or
• deploying it somewhere it stays running (a small always-on server/VPS/hosting service)

That, plus the actual ElevenLabs agent configuration, is intentionally a separate next step — not part of this build.