Invoice4U MCP by Agente

An unofficial, third-party Model Context Protocol server that gives any MCP-compatible agent safe, typed access to an Invoice4U account — searching documents and customers, and creating receipts linked to paid invoices.

• Unofficial: this is a community integration, not affiliated with, endorsed by, or supported by Invoice4U. Invoice4U names are used nominatively to describe what the server connects to. No Invoice4U trademarks or logos are used without permission.

• TypeScript / Node.js 24 LTS / MIT · stdio transport · local self-hosted — Agente never custodies your Invoice4U credentials.

• Read-only by default: the single write tool (receipt creation) is not registered in tools/list unless INVOICE4U_ALLOW_WRITES=true.

• English README · Hebrew README.he.md

Quick start

{
  "mcpServers": {
    "invoice4u": {
      "command": "npx",
      "args": ["-y", "@agente-dev/invoice4u-mcp"],
      "env": {
        "INVOICE4U_API_TOKEN": "your-api-key",
        "INVOICE4U_ENV": "qa",
        "INVOICE4U_ALLOW_WRITES": "false"
      }
    }
  }
}

INVOICE4U_ENV must be explicitly qa or production — it never silently defaults to production. Start against QA; it is the safe documented starting configuration.

Related MCP server: mcp-server-smallinvoice

Tools (v0.1 surface)

Read tools declare readOnlyHint: true, idempotentHint: true. The write tool declares readOnlyHint: false, destructiveHint: false, idempotentHint: true — idempotency holds only because a stable apiIdentifier is mandatory and duplicate or uncertain outcomes resolve through identifier lookup. A timeout after submitting a write is never blindly retried: the server first queries by apiIdentifier and retries only when the lookup proves no document exists.

Money is expressed as decimal strings at the MCP boundary ("12500.00"), never JavaScript floats. Invoice4U responses that return HTTP 200 while carrying application errors in the Errors collection are normalized into a typed error model — never reported as success.

Configuration

Credentials live only in environment variables — the token is never accepted as a tool argument, never returned, never logged.

See .env.example. Only reviewed official Invoice4U hosts are contacted — there is no arbitrary base-URL escape hatch.

Safety model

• Read-only by default — the write tool is omitted from tools/list entirely unless writes are explicitly enabled.

• Idempotent writes — mandatory stable apiIdentifier; resubmitting the same request cannot create a second receipt.

• Verified writes — every write re-fetches the receipt and referenced invoices, returning previous/new balances and statuses as structured output.

• No blind retries on uncertain write outcomes; resolution goes through apiIdentifier lookup.

• Secret hygiene — no tokens or customer PII in logs at normal levels; QA fixtures contain no real customer data.

• No money movement — creating a receipt records money already received; the server cannot initiate payments or charge cards.

Status

Implemented — v0.1 surface. Eight tools (7 read + 1 gated write) are implemented and registered as described in the Tools table above. Coverage is tracked in coverage-manifest.json, with details in docs/.

• QA status: read tools are verified against the Invoice4U API reference plus contract tests (120 unit + contract tests green). Live QA integration is BLOCKED pending credentials — there is no public Invoice4U sandbox, and exercising apiqa.invoice4u.co.il requires a real QA org account + API token. The gated smoke test (tests/integration/qa.spec.ts) is skipped without a token; see docs/qa-testing.md.

• npm package pending: publication awaits the trusted-publishing link for @agente-dev/invoice4u-mcp on npmjs.com.

License

MIT — see LICENSE. © Agente Dev LTD. Not affiliated with Invoice4U.