Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@staffing-math How many people do I need for 4,000 cases a week at 12 minutes each with 30% shrinkage?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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)
Arithmetic
1. Work per week = 4,000 cases x 12 min / 60 = 800.0 hours
2. Productive hours per FTE = 40 x (1 - 0.3) = 28.00 hours
3. Planned hours per FTE at 85% occupancy = 28.00 x 0.85 = 23.80 hours
4. FTE needed = 800.0 / 23.80 = 33.61
5. 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.Month | Weekly volume | FTE needed | Reqs to open | Hires counting | Expected leavers | FTE on hand | Spare (+) / short (-) |
Month 1 | 4,000 | 33.61 | 4 | 0 | 0.00 | 34.00 | +0.39 |
Month 2 | 4,200 | 35.29 | 1 | 0 | 0.00 | 34.00 | -1.29 |
Month 3 | 4,410 | 37.06 | 2 | 4 | 0.00 | 38.00 | +0.94 |
Month 4 | 4,631 | 38.91 | 2 | 1 | 0.00 | 39.00 | +0.09 |
Month 5 | 4,862 | 40.86 | 3 | 2 | 0.00 | 41.00 | +0.14 |
Month 6 | 5,105 | 42.90 | 2 | 2 | 0.00 | 43.00 | +0.10 |
Month 7 | 5,360 | 45.05 | 2 | 3 | 0.00 | 46.00 | +0.95 |
Month 8 | 5,628 | 47.30 | 3 | 2 | 0.00 | 48.00 | +0.70 |
Month 9 | 5,910 | 49.66 | 2 | 2 | 0.00 | 50.00 | +0.34 |
Month 10 | 6,205 | 52.15 | 3 | 3 | 0.00 | 53.00 | +0.85 |
Month 11 | 6,516 | 54.75 | 3 | 2 | 0.00 | 55.00 | +0.25 |
Month 12 | 6,841 | 57.49 | 3 | 3 | 0.00 | 58.00 | +0.51 |
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.
Related MCP server: Agent Reliability MCP Server
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.gitOpen 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.
As a plugin, from inside Claude Code:
/plugin marketplace add bsunter93/staffing-math
/plugin install staffing-math@staffing-mathOr as a plain MCP server:
claude mcp add staffing-math -- node /full/path/to/staffing-math/dist/staffing-math.mjsgemini extensions install https://github.com/bsunter93/staffing-mathgemini-extension.json in the repo runs the same bundled server. Gemini CLI shows the tools' text answers; it doesn't draw the plan view.
These connect to a remote server over Streamable HTTP at a public HTTPS URL. The hosted one is free to use, needs no sign-in and stores nothing:
https://staffing-math.vercel.app/mcpTo run your own, start the server in HTTP mode:
node dist/staffing-math.mjs --http --port 3000It 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.
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 --prodvercel.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.
Tool | Required | Optional, with defaults |
|
|
|
|
| the three above, |
|
|
|
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.
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.
FTE needed each month = weekly hours of work / (hours per FTE x (1 - shrinkage) x target occupancy).
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.
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.
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.
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.
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.
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.
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.
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 install
npm test # upstream engine tests plus this repo's own
npm run check:vendor # confirms vendor/ still matches upstream
npm run build # rebuilds dist/staffing-math.mjsThe 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.
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.
MIT
Agents needed on a live queue (phone, chat) to answer a target share of contacts within a target time, using Erlang C. Give contacts per hour for the interval being staffed (usually the busiest hour) and handle time in seconds. Returns agents needed, the service level at that number and at one fewer, chance of waiting, occupancy, and people to schedule after shrinkage. Use required_fte for case or ticket work with no answer-time target.
| Name | Required | Description | Default |
|---|---|---|---|
| shrinkage | No | Share of paid time agents are off the queue. Converts agents to people scheduled. Default 0.3. | |
| service_level | No | Share of contacts to answer within the target time. Default 0.8. | |
| contacts_per_hour | Yes | Contacts arriving per hour in the interval being staffed. | |
| handle_time_seconds | Yes | Average handle time in seconds: talk plus after-contact work. | |
| answer_within_seconds | No | Target answer time in seconds. Default 20. |
| Name | Required | Description |
|---|---|---|
| notes | Yes | |
| steps | Yes | |
| agents | Yes | |
| answer | Yes | |
| engine | Yes | |
| inputs | Yes | |
| occupancy | Yes | |
| people_to_schedule | Yes | |
| offered_load_erlangs | Yes | |
| probability_of_waiting | Yes | |
| service_level_at_agents | Yes | |
| service_level_one_fewer | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds what the computation returns (service level at n and n-1, wait probability, occupancy, shrinkage-adjusted headcount), which conveys that this is a sensitivity-producing calculation rather than a single number. It does not mention edge behavior such as what happens at very low load or invalid target/service-level combinations, so it adds only modest context beyond the structured fields and the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the purpose, then inputs, then outputs, then the sibling exclusion. Nothing is redundant and no sentence could be dropped without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only calculation tool with a full input schema and an output schema, the description supplies everything an agent needs: what it computes, how to parameterize the inputs, what comes back conceptually, and when to prefer the sibling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description still earns credit by adding interpretation the schema lacks: that contacts_per_hour should represent the busiest interval being staffed, that shrinkage converts agents into people to schedule, and that answer-time targets are optional in spirit for non-queue work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific computation (agents needed) on a specific resource (live phone/chat queue) with the method named (Erlang C), and explicitly distinguishes itself from the sibling required_fte for case/ticket work with no answer-time target.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives the condition to use it (live queue with a target share answered within a target time), the input heuristic (contacts per hour for the busiest hour), and names the alternative when there is no answer-time target. The routing decision is fully determined from the description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Month-by-month hiring plan: how many requisitions to open each month so FTE on hand keeps up with FTE needed, after attrition, time to hire and ramp. Give weekly_volume with monthly_growth (0.05 means 5% a month, compounding), or weekly_volume_by_month. Unknown inputs fall back to stated defaults: current headcount defaults to what month 1 needs, attrition to 0, time to hire to 2 months, ramp to 0. When attrition is assumed, the result also gives the plan at 15% and 30%. Give hires_in_flight for people already hired or in the pipeline. Returns the plan table, totals, the arithmetic, and which inputs were assumed. A hire counts as zero capacity until fully ramped.
| Name | Required | Description | Default |
|---|---|---|---|
| months | No | Plan length in months when using monthly_growth. Default 12. | |
| shrinkage | No | Share of paid time not available for the work: PTO, sick time, training, meetings. 0.30 means 30%. Default 0.3. | |
| ramp_months | No | Months from start date to full productivity. Default 0. | |
| start_month | No | First month of the plan as YYYY-MM, used only to label months. | |
| weekly_volume | No | Weekly volume in month 1. Use with monthly_growth. | |
| monthly_growth | No | Month-over-month change in weekly volume. 0.05 means 5% a month. Default 0. | |
| hires_in_flight | No | People already hired or in the pipeline, and the month they start counting. These are the only way to cover months before a new requisition can land. | |
| annual_attrition | No | Share of the team that leaves in a year. 0.25 means 25%. Default 0. | |
| minutes_per_case | Yes | Average handling time per case, in minutes. | |
| target_occupancy | No | Share of available time you plan to keep people busy with the work. Default 0.85. | |
| current_headcount | No | FTE on the team today. Default: what month 1 needs, rounded up. | |
| hours_per_fte_week | No | Paid hours per full-time person per week. Default 40. | |
| time_to_hire_months | No | Months from opening a requisition to the start date. Default 2. | |
| weekly_volume_by_month | No | Average weekly volume in each month of the plan, instead of weekly_volume and monthly_growth. |
| Name | Required | Description |
|---|---|---|
| notes | Yes | |
| steps | Yes | |
| answer | Yes | |
| engine | Yes | |
| inputs | Yes | |
| months | Yes | |
| most_spare | Yes | |
| total_reqs | Yes | |
| attrition_range | Yes | |
| expected_leavers | Yes | |
| lookahead_months | Yes | |
| months_with_spare | Yes | |
| fte_needed_last_month | Yes | |
| fte_needed_first_month | Yes | |
| first_month_hires_can_count | Yes | |
| months_short_before_hires_land | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare a safe, read-only, idempotent, closed-world computation, so the description's burden is lower, and it still adds real behavior: unknown inputs fall back to stated defaults, the response is accompanied by a 15% and 30% attrition sensitivity, and it reports which inputs were assumed. The rule that a hire counts as zero capacity until fully ramped is a genuinely useful behavioral disclosure. It does not cover runtime characteristics such as compute cost or limits on large month arrays.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded in the first sentence, followed by input-mode selection, defaults, sensitivity behavior, and return contents in a logical order with no filler. It is dense but appropriately so for a 14-parameter planning model; only minor tightening would help.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-parameter computational tool with annotations and an output schema, the description covers the ambiguity an agent would actually hit: default resolution, the two mutually exclusive volume modes, pipeline hires, ramp treatment, and what the response contains. The remaining gap is the absent relationship to its sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the interplay of parameters rather than repeating them — monthly_growth is stated to be compounding, current_headcount defaults to month 1's requirement rounded up, and hires_in_flight is framed as the only way to cover months before a new requisition can land. It stays silent on shrinkage, target_occupancy, and hours_per_fte_week, but those are documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names the resource and the computed output precisely: month-by-month requisitions to open so FTE on hand tracks FTE needed after attrition, time to hire, and ramp. That is far more specific than a tautology. It does not, however, distinguish itself from the siblings required_fte and erlang_staffing, so an agent must infer which of the three to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Guidance is given on how to drive the model (supply weekly_volume with monthly_growth, or weekly_volume_by_month; use hires_in_flight for people already hired) and on default fallbacks for unspecified inputs. What is missing is when-to-use-this-vs-alternatives: no sibling is named and no exclusion is stated, so routing among required_fte, erlang_staffing, and this tool is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
How many people a steady workload needs. Give weekly volume and minutes per case; shrinkage, target occupancy and hours per week fall back to stated defaults. Returns FTE, people to staff (rounded up), every input marked given or assumed, and the arithmetic with numbers filled in. Use hiring_plan when volume changes over time or the question is about hiring, and erlang_staffing for live queues with an answer-time target.
| Name | Required | Description | Default |
|---|---|---|---|
| shrinkage | No | Share of paid time not available for the work: PTO, sick time, training, meetings. 0.30 means 30%. Default 0.3. | |
| weekly_volume | Yes | Cases, tickets or items arriving per week. | |
| minutes_per_case | Yes | Average handling time per case, in minutes. | |
| target_occupancy | No | Share of available time you plan to keep people busy with the work. Default 0.85. | |
| hours_per_fte_week | No | Paid hours per full-time person per week. Default 40. |
| Name | Required | Description |
|---|---|---|
| fte | Yes | |
| notes | Yes | |
| steps | Yes | |
| answer | Yes | |
| engine | Yes | |
| inputs | Yes | |
| people | Yes | |
| weekly_work_hours | Yes | |
| fte_per_extra_minute | Yes | |
| planned_hours_per_fte_week | Yes | |
| productive_hours_per_fte_week | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior. The description adds useful context about defaults and the returned arithmetic, but it does not go much beyond what the annotations and output schema already establish.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose, then inputs/defaults, then return values, then alternatives. Every sentence is useful and there is no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema and annotations, the description is complete enough for an agent to select and invoke the tool correctly. It covers purpose, required inputs, defaults, return shape, and sibling alternatives.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all five parameters, including defaults and ranges. The description reinforces which inputs are required and which fall back to defaults, but adds little semantic detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific computation: how many people a steady workload needs from weekly volume and minutes per case. It clearly scopes the tool to steady workloads, which distinguishes it from the sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly names when to use the alternatives: hiring_plan for changing volume or hiring questions, and erlang_staffing for live queues with an answer-time target. It also tells the caller which inputs to provide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0erlang_staffinghiring_planrequired_fteScored across 3 tools
Each tool has a clearly separate use case: required_fte for steady-state headcount, hiring_plan for time-varying hiring and attrition, and erlang_staffing for live queues with answer-time targets. Descriptions explicitly cross-reference the alternatives, so an agent can select reliably.
All three names use snake_case and descriptive staffing-domain nouns, giving a predictable pattern even though they are not verb_noun. There are no mixed conventions or vague labels.
Three tools is tightly scoped to staffing math, and each covers a distinct calculation. None feels redundant or conspicuously missing at the set level.
The set covers steady FTE, growth/attrition hiring, and Erlang queue staffing, with defaults and assumptions surfaced. Some adjacent needs such as cost/budget modeling or roster generation are absent, but core staffing-math workflows are covered.
Field operations on a deterministic solver — run jobs, crews & fleet from Claude or ChatGPT.
Deterministic what-if & scenario simulation for AI agents: projections, sensitivity & break-even.
Claude, connected to your own Oracle EPM. Each person as themselves, every call checked and logged.
Ask Claude or ChatGPT about your team in PapaHR: who is away, hiring, probation, eNPS, HR costs.