efile.technology

This documentation describes a mock MCP server. It does not file with the IRS and does not connect to any IRS system.

Quickstart: mcp-efile-mock

MOCK SERVER. It does not file with the IRS, does not connect to any IRS system, and makes no network calls. Nothing here is IRS-approved. Use fake data only (EINs starting 00, SSNs like 000-00-0000). Rule codes are illustrative unless the result's basis names Pub 4164. Generated XML is illustrative and is not schema-valid.

Documented against mcp-efile-mock 0.2.0 (verified 2026-10-23).

1. Install and build

Requires Node 22 or newer. The mock server source is not distributed from this site; these steps assume you already have a copy of its server/ folder.

cd path/to/mcp-efile-mock/server
npm install
npm run build        # compiles src/ to dist/
npm test             # optional: builds, then runs vitest incl. a stdio smoke test

2. Register with Claude Code

Use the absolute path to your built dist/index.js (the package is private, so there is no npm install of it):

claude mcp add efile-mock -- node /absolute/path/to/mcp-efile-mock/server/dist/index.js
claude mcp list            # confirm efile-mock is connected
claude mcp remove efile-mock   # to uninstall

The server speaks MCP over stdio. It logs one line to stderr on start (mcp-efile-mock running on stdio (MOCK ONLY ...)); stdout is reserved for the protocol. State (submissions) lives in memory only and is lost when the process exits, so each new Claude session starts empty and the "duplicate" rule only sees submissions from the current process.

3. First calls

Tools are exposed as mcp__efile-mock__<tool> in Claude Code.

  1. list_supported_forms with {}. Returns the form list and each form's top-level field names with required flags. Modeled by the mock: 941, 944, 4868, 7004, 941-X. Planned: 943. Not available: 940, 945, 1120-S, 8868.
  2. validate_return with a fake Form 941 (this exact input was run against the built server and returned valid: true, no errors, no warnings):
{
  "formType": "941",
  "data": {
    "filer": { "ein": "00-0000000", "businessName": "Test Co Mock" },
    "taxYear": 2025, "quarter": 1, "numberOfEmployees": 5,
    "wages": 100000, "fitWithheld": 10000,
    "ssWages": 100000, "medicareWages": 100000,
    "totalDeposits": 25300, "depositSchedule": "monthly",
    "monthlyLiability": { "month1": 8433.33, "month2": 8433.33, "month3": 8433.34 }
  }
}
  1. build_return_xml with the same arguments: returns illustrative XML. xsd.status will be not_available (the official IRS schemas are not installed), which means the XML was not schema-validated.
  2. mock_submit_return with the same arguments: returns a 20-digit submissionId and status: "Received".
  3. get_acknowledgement with { "submissionId": "<id>" }: returns status: "Accepted" and kind: "Acknowledgement" for the fixture above. "Accepted" here is a mock result only.

Try breaking it: change month1 to 8000 (error F941-032), use EIN 12-3456789 (error R0000-148), or submit the same return twice (second gets R0000-902-01). See the error catalog.

Where to go next