Staffing Math

Staffing Math

An MCP server that gives Claude and ChatGPT exact staffing math. It has three tools:

• required_fte: how many people a steady workload needs.
• hiring_plan: how many requisitions to open each month as volume changes, after attrition, time to hire and ramp.
• erlang_staffing: how many agents a phone or chat queue needs to hit an answer-time target (Erlang C).

The model does the talking. The tools do every calculation and return it with the answer: each input marked given or assumed, and the arithmetic with the numbers filled in. You can check any answer with a calculator.

In Claude and ChatGPT, hiring_plan also draws its answer: FTE needed against FTE on hand by month, the short months hatched, and the requisitions to open underneath. Sliders for growth, attrition, time to hire, ramp, shrinkage and headcount rerun the plan on the server as you move them, and the model is told what you changed.

The math is the engine from the Operating Model Simulator, copied unchanged into vendor/ along with its own tests.

To use it without installing anything, add https://staffing-math.vercel.app/mcp as a connector. Steps and examples: bensunter.com/staffing-math.html.

Worked example

I handle 4,000 cases a week at 12 minutes each with 30% shrinkage. How many people do I need, and what's my hiring plan if volume grows 5% a month?

required_fte returns:

Answer: 33.61 FTE, so 34 people.
Inputs- weekly volume: 4,000 cases (given)- minutes per case: 12 (given)- shrinkage: 30% (given)- target occupancy: 85% (assumed)- hours per FTE per week: 40 (assumed)
Arithmetic1. Work per week = 4,000 cases x 12 min / 60 = 800.0 hours2. Productive hours per FTE = 40 x (1 - 0.3) = 28.00 hours3. Planned hours per FTE at 85% occupancy = 28.00 x 0.85 = 23.80 hours4. FTE needed = 800.0 / 23.80 = 33.615. People to staff = 33.61 rounded up = 34
Each extra minute per case adds 2.80 FTE.

hiring_plan with the same inputs and 5% monthly growth returns this answer and table, plus the same inputs and arithmetic blocks:

Answer: open 30 requisitions over 12 months, 4 of them in month 1.FTE needed goes from 33.61 in month 1 to 57.49 in month 12. Expected leavers over the plan: 0.0.Requisitions opened in months 11 and 12 are for hires who count in months 13 and 14, assuming the 5% monthly growth continues.Month 2 is short and new hires can't fix that: the earliest a requisition opened now counts is month 3. Covering it takes overtime, contractors or moving people. People already hired or in the pipeline can count earlier: give them as hires_in_flight.Attrition was assumed to be 0%. At 15% a year this plan needs 38 requisitions; at 30%, 48. Ask for the team's real rate.Current headcount was assumed to be exactly what month 1 needs (34), as if the team is fully staffed today. If it has fewer people, give current_headcount.

The prompt didn't give target occupancy, hours per week, current headcount, attrition, time to hire or ramp, so the tool used its defaults and listed each one as assumed. Attrition and headcount move the answer most, so the result spells those two out, with the plan at 15% and 30% attrition alongside. Claude is told to say so and offer to rerun with real numbers. With 30 people today, 25% annual attrition and a month of ramp, the same forecast needs 53 requisitions instead of 30, 12 of them in month 1, and months 1 to 3 are short before any hire can count.

Checking it by hand: month 12 volume is 4,000 x 1.05^11 = 6,841 cases a week. That's 6,841 x 12 / 60 = 1,368 hours, and 1,368 / 23.80 = 57.49 FTE.

Install

The server is one file, dist/staffing-math.mjs, and needs Node 18 or later. Clone the repo first:

git clone https://github.com/bsunter93/staffing-math.git

Claude Desktop

Open Settings, then Developer, then Edit Config, and add the server to claude_desktop_config.json. Use the full path to your clone:

{  "mcpServers": {    "staffing-math": {      "command": "node",      "args": ["/full/path/to/staffing-math/dist/staffing-math.mjs"]    }  }}

Restart Claude Desktop. The three tools appear under the tools menu in a new chat.

To install it as a Desktop extension instead, run npm run pack and double-click the staffing-math.mcpb it writes.

Claude Code

As a plugin, from inside Claude Code:

/plugin marketplace add bsunter93/staffing-math/plugin install staffing-math@staffing-math

Or as a plain MCP server:

claude mcp add staffing-math -- node /full/path/to/staffing-math/dist/staffing-math.mjs

Gemini CLI

gemini extensions install https://github.com/bsunter93/staffing-math

gemini-extension.json in the repo runs the same bundled server. Gemini CLI shows the tools' text answers; it doesn't draw the plan view.

ChatGPT, Gemini and Claude custom connectors

These connect to a remote server over Streamable HTTP at a public HTTPS URL. The hosted one is free to use and needs no sign-in. It saves none of your numbers; it counts calls by day, app and tool (see Usage counts):

https://staffing-math.vercel.app/mcp

To run your own, start the server in HTTP mode:

node dist/staffing-math.mjs --http --port 3000

It listens on http://127.0.0.1:3000/mcp. Put it behind HTTPS (a host, a reverse proxy, or a tunnel such as cloudflared tunnel --url http://localhost:3000), then add https://your-host/mcp as a connector with no authentication:

• ChatGPT: Plugins, then Add, then Add custom MCP server, with no authentication. ChatGPT draws the plan view. After an update, Refresh tools in the plugin's settings picks up new inputs.
• Gemini: Connectors, then Custom. Gemini shows the text answers.
• Claude: Settings, Connectors, Add custom connector. Use --host 0.0.0.0 when it runs on a server.

The HTTP mode is stateless. Each request gets a fresh server, so it scales out without sessions.

Hosting it

api/index.mjs is the same server as a single Web-standard fetch handler (src/fetch.ts), built by npm run build. On Vercel:

npx vercel deploy --prod

vercel.json sends every path to that one function and tells Vercel there's no framework, nothing to install and nothing to build, so a project Vercel once guessed was something else still deploys. .vercelignore uploads only api/ and vercel.json. Dragging a folder with just those two onto the project page in Vercel's dashboard deploys the same thing without the CLI. The endpoint is https://<project>.vercel.app/mcp. The same handler runs on Cloudflare Workers, Deno or Bun. On Workers' free plan, a 36-month plan with attrition can pass the 10ms CPU limit per request; the paid plan doesn't have that problem.

Tools

Fractions are fractions: 0.30 means 30%. A value of 30 for shrinkage is rejected with a message saying so.

Every result has a text block for the model and a structuredContent copy with the same numbers, the inputs and the steps. All three tools are read-only, make no network calls and store nothing.

Usage counts

The hosted server at staffing-math.vercel.app adds one to a counter for each request: the day (UTC), the app (the first word of its User-Agent, such as openai-mcp) and what it asked for (initialize, tools_list, a tool name, or view). It also counts the app name a client sends when it connects. It never saves tool inputs, results, IP addresses or full User-Agent strings. The counts are public at /stats.

Counting runs only when an Upstash Redis REST URL and token are set (KV_REST_API_URL and KV_REST_API_TOKEN, or the UPSTASH_REDIS_REST_ pair). Your own copy, over stdio or HTTP, counts nothing. If the store is slow or down, the answer still goes out; see src/usage.ts.

The plan view

hiring_plan carries an MCP Apps view, ui://staffing-math/hiring-plan.html: one HTML file with its script inlined and no outside requests. Hosts that support MCP Apps draw it under the answer; other hosts ignore it and show the text.

• The headline and the line under it are the answer in words, and screen readers hear them again after every change.
• The chart has a text description. Point at a month, or focus the chart and use the arrow keys, to read that month in a sentence.
• Every control is a labeled native slider or number field, so it works from the keyboard.
• "Show the numbers" opens the full table.
• It follows the host's light or dark theme.

The view never calculates. Moving a control calls hiring_plan again with the new arguments and draws what comes back.

How the hiring plan works

1. FTE needed each month = weekly hours of work / (hours per FTE x (1 - shrinkage) x target occupancy).
2. Attrition is applied monthly at the rate that compounds to the annual figure: 1 - (1 - annual)^(1/12). Leavers are an expected value, so headcount can be fractional.
3. A requisition opened in month m counts as capacity from month m + time to hire + ramp. Until it's fully ramped a hire counts as zero, so the plan errs toward opening requisitions early.
4. Walking forward from the first month a hire can count, wherever FTE on hand is below FTE needed, the solver opens the shortfall in whole people in the month that lands them in time, then reruns the engine.
5. Months before the first possible landing can't be fixed by new requisitions. The tool says which ones and by how much. People already hired or in the pipeline can: hires_in_flight takes how many and the month each group starts counting, and the plan opens only what's still missing.
6. Requisitions opened near the end of the plan land after it. With a growth rate the solver carries the forecast past the last month so those requisitions still get planned, and says so. With a month-by-month forecast it plans nothing past the last month you gave.
7. A month with at least one whole FTE more than it needs is spare. The tool names the most overstaffed month, and the view shades every spare month. Hiring can't fix a spare month; it shows where demand dips below the people already there.
8. When attrition isn't given, the plan is rerun at 15% and 30% a year and both totals are reported. Those are reference points for the conversation, not benchmarks.

The tests check that the plan covers every coverable month and that removing any single requisition leaves some month short, so it never hires more than the forecast needs.

Where the math comes from

vendor/operating-model-simulator/ is a byte-for-byte copy of the Simulator's engine at commit 758c9d7: the monthly model (run()), Erlang B and C with a stable recursion that doesn't overflow past 170 agents, and the calendar helpers. required_fte and hiring_plan build a one-team model and call run(); erlang_staffing calls staffFor, serviceLevel and erlangC. This repo adds the weekly-to-monthly conversion, the hiring solver and the MCP server around them.

npm installnpm test               # upstream engine tests plus this repo's ownnpm run check:vendor   # confirms vendor/ still matches upstreamnpm run build          # rebuilds dist/staffing-math.mjs

The tests include hand calculations for each tool, a textbook Erlang C written independently to check the engine against, and runs over all three transports: in memory, Streamable HTTP, and the built file over stdio.

Limits

Erlang C assumes nobody hangs up while waiting and that arrivals are steady across the interval, so staff the busiest hour. There's no cost or budget, no multi-team routing, and no seasonality inside a month. The Operating Model Simulator covers multiple teams, routing between them and cost.

License

MIT