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., "@malaysia-payroll-mcp Calculate EPF, SOCSO, EIS and PCB for a resident employee on RM5,000 a month"
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 works out Malaysian statutory payroll deductions (EPF, SOCSO, EIS and MTD/PCB) for one resident employee's monthly salary, and cites the official rate table or rule behind every number.
Status: pre-release. EPF, SOCSO, SKBBK and EIS are in; MTD and net pay come next. Nothing is published to npm yet.
Tool | What it works out |
| EPF employee and employer contributions, from the Third Schedule in effect |
| SOCSO, SKBBK (Lindung 24 Jam) and EIS contributions, from the PERKESO tables in effect |
Every result echoes the pay period it used (the current month in Malaysia if you don't pass one), and carries citations, an explanation rendered from them, and a disclaimer.
Related MCP server: cukaimax-tax-authority
Every rate table the tools read is also a read-only resource, as JSON with amounts in sen: payroll://tables/{kind}/{effectiveFrom}, where kind is epf, socso, skbbk or eis. For example, payroll://tables/epf/2025-10-01 is the EPF Third Schedule from 1 Oct 2025. resources/list shows them all, and the template completes both parts.
Not tax advice and not LHDN-verified. Fixed monthly salaries only: overtime, commission, bonuses and arrears aren't supported.
Architecture: structure, stack and key decisions
Glossary: the domain terms used in code and docs
Official sources, with effective and retrieval dates
Golden test cases, worked by hand from those sources
Rate tables as CSV, the source of truth for every lookup
Needs Node 22 or later and pnpm (the version is pinned in package.json).
pnpm install
pnpm check # generated tables, Biome lint and format check, tsc, Vitest
pnpm gen:tables # regenerate src/tables/generated/ after editing docs/data/
pnpm test:coverage # tests with v8 coverage
pnpm build # compile to dist/To change a rate, edit or add a CSV in docs/data/ (with its entry in docs/data/sources.json), run pnpm gen:tables and commit both. Never edit src/tables/generated/ by hand: CI rejects it (ADR 0003).
Works out the monthly EPF (KWSP) employee and employer contributions for one employee in Malaysia, from the EPF Third Schedule in effect for the pay period, and cites the band used. Fixed monthly salaries only.
| Name | Required | Description | Default |
|---|---|---|---|
| age | Yes | The employee's age in whole years. | |
| payPeriod | No | The calendar month the salary is paid for, as YYYY-MM. It decides which rate tables apply. Defaults to the current month in Malaysia. | |
| citizenship | Yes | malaysian, permanent_resident, or non_malaysian (a foreign worker without PR). | |
| monthlySalary | Yes | Monthly salary in RM, at most 2 decimal places: basic pay plus fixed allowances. Excludes overtime, commission, bonuses and arrears. | |
| registeredWithEpfBefore1Aug1998 | No | Only for non_malaysian: true if the employee registered with EPF before 1 Aug 1998, which puts them on the Malaysian rates. Defaults to false. |
| Name | Required | Description |
|---|---|---|
| part | Yes | The EPF Third Schedule part applied. |
| total | Yes | RM |
| employee | Yes | RM, deducted from pay. |
| employer | Yes | RM, paid on top of pay. |
| citations | Yes | |
| payPeriod | Yes | |
| disclaimer | Yes | |
| explanation | Yes | |
| monthlySalary | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: rates come from the Third Schedule in effect for the pay period, the response cites the band used, and it is limited to fixed monthly salaries.
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?
A single front-loaded sentence that names the calculation, the governing schedule, the cited output, and the scope restriction. Nothing redundant and no filler.
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?
With a full output schema and 100% param coverage, the description doesn't need to explain return values, and it correctly covers source-of-truth and scope. Minor gaps: no mention of rounding/precision behavior or what happens for out-of-range or unsupported inputs.
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 every parameter including the payPeriod rate-table selection and the non_malaysian pre-1998 flag. The description adds only the salary framing ('fixed monthly salaries only'); baselining at 3 is correct here.
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 verb and resource ('Works out the monthly EPF (KWSP) employee and employer contributions') and scopes it to one employee in Malaysia from the Third Schedule. It doesn't explicitly contrast with the sibling calculate_socso_eis, though the domain difference (EPF vs SOCSO/EIS) is obvious enough that an agent won't confuse them.
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?
'Fixed monthly salaries only' is a clear exclusion that tells the agent when not to use it (variable pay, bonuses, arrears). It stops short of naming the sibling as the tool for other statutory deductions or of stating how to handle non-fixed-income cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Works out the monthly SOCSO (PERKESO, Act 4), SKBBK (Lindung 24 Jam) and EIS (Act 800) contributions for one employee in Malaysia, from the PERKESO tables in effect for the pay period, and cites the row used for each. Fixed monthly salaries only.
| Name | Required | Description | Default |
|---|---|---|---|
| age | Yes | The employee's age in whole years. | |
| payPeriod | No | The calendar month the salary is paid for, as YYYY-MM. It decides which rate tables apply. Defaults to the current month in Malaysia. | |
| citizenship | Yes | malaysian, permanent_resident, or non_malaysian (a foreign worker without PR). | |
| skbbkStatus | No | SOCSO's 24-hour protection scheme (SKBBK, Lindung 24 Jam). Everyone is covered by default; opted_out only if PERKESO approved the employee's opt-out, which foreign workers can't do. Defaults to covered. | |
| monthlySalary | Yes | Monthly salary in RM, at most 2 decimal places: basic pay plus fixed allowances. Excludes overtime, commission, bonuses and arrears. | |
| eisPayableBefore57 | No | Required for employees aged 57 to 59: true if EIS contributions were payable for them before they turned 57 (even if never paid). Can't be worked out from age. |
| Name | Required | Description |
|---|---|---|
| eis | Yes | |
| skbbk | Yes | |
| socso | Yes | |
| totals | Yes | |
| citations | Yes | |
| payPeriod | Yes | |
| disclaimer | Yes | |
| explanation | Yes | |
| skbbkStatus | Yes | |
| monthlySalary | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint=false. The description adds genuinely new behavior: contributions are derived from the rate tables in effect for the pay period, and the response cites the table row used per contribution — traceability an agent would otherwise not expect.
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?
A single front-loaded sentence with the verb, the three contribution types, the scope, the rate-table dependency, and the exclusion all present. No clause is redundant with the title or schema.
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?
All required context is covered: the statutory schemes, the one-employee scope, the fixed-salary restriction, the pay-period table versioning, and the citation behavior. An output schema exists, so return values need no explanation here.
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 all six parameters (including the payPeriod table-selection and the 57–59 EIS flag) are already documented. The description reinforces salary composition ('fixed monthly salaries only') and pay-period-driven table selection but adds no parameter detail the schema lacks.
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?
Names a specific computation (monthly SOCSO/SKBBK/EIS contributions) with the exact statutory basis (Act 4, Act 800, Lindung 24 Jam) and scope (one employee, Malaysia). The resource is distinct enough from the solo sibling calculate_epf that no agent could confuse the two.
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?
States a hard eligibility boundary — 'Fixed monthly salaries only' — which tells the agent when not to call it, and scopes output to one employee. It does not explicitly name an alternative tool or the procedure for non-fixed pay, so it stops short of full routing guidance.
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.0.0calculate_epfcalculate_socso_eisScored across 2 tools
The two tools target completely disjoint statutory schemes (EPF/KWSP vs SOCSO/SKBBK/EIS/PERKESO), so there is no realistic risk of misselection. Descriptions reinforce the distinction by naming the governing acts and tables used.
Both tools follow the same verb_noun snake_case pattern (calculate_epf, calculate_socso_eis) and start with the same verb, making the set predictable.
Two tools is thin for a server labeled as a payroll MCP; it only covers statutory contribution calculators. It is defensible as a narrow contribution-calculation server, but leaves the 'payroll' scope largely unserved.
Core payroll components are absent: no PCB/MTD monthly tax deduction, no HRD Corp levy, no combined gross-to-net or total statutory deduction tool, and no batch/multi-employee support. An agent could compute EPF and SOCSO/EIS but would dead-end on income tax and final net pay.
Source-linked Malaysian individual and sole-proprietor tax guidance for AI agents.
Malaysian SME accounting, e-Invoice and payroll for your AI. 64 tools; writes are approved drafts.
Source-backed Sri Lanka payslip tools for APIT/PAYE, EPF, ETF, stamp duty, and net pay.
Deterministic Japan statutory calculations with cited primary sources: net pay, social insurance, income walls, bonus, consumption tax, business days, overtime, retirement tax, payslip audit and crypto tax. x402 (USDC on Base), no API key; failed calls are never charged.
