Switches, limits and pitfalls

All settings come from environment variables and belong in the env block of the client configuration. Each has a usable default; the server runs without an env block.

The switches

Variable	Default	Effect
INVOICEFLAIR_MCP_ROOT	none	confines every read and write access to this directory. Recommended
INVOICEFLAIR_MCP_OUTPUT	a temp subfolder	where results go when no target path is given
INVOICEFLAIR_MCP_MAX_BYTES	15728640 (15 MB)	upper limit per file read
INVOICEFLAIR_MCP_INLINE_LIMIT	32768	up to this size a text result also comes back in the answer
INVOICEFLAIR_MCP_MAX_FINDINGS	25	findings per validation answer; the rest is reachable through findings_offset
INVOICEFLAIR_MCP_TAGGED_PDF	off	produce accessible invoices (tagged PDF / PDF-UA)
INVOICEFLAIR_MCP_USAGE	on	write a usage log (event lines only)
INVOICEFLAIR_MCP_USAGE_DIR	<app>/usage	where the log goes
INVOICEFLAIR_MCP_USAGE_ARTIFACTS	off	write the invoice contents as well

--help prints the list along with the values currently in effect.

On ROOT

The server accesses files with the rights of whoever started it — which is normal for a local MCP server.

ROOT limits the accidental reach

A model that invents a path for itself then does not reach across the whole disk. Recommended for productive use.

On the log

The usage log writes event lines only — tool, duration, format, finding counts. The invoice contents stay out of it, and that is deliberate: the local server is the answer to “our invoices do not leave the building”; it must not copy them into a second directory unasked.

INVOICEFLAIR_MCP_USAGE_ARTIFACTS=1 switches that on explicitly, for instance to build a quality corpus of your own.

What the server deliberately does not do

These points stand as a limit, not as a promise for later.

• No invoice data capture from ordinary PDFs. A hybrid PDF is read — there is a data record inside it; turning an ordinary PDF invoice into data is a different task and remains reserved to the portal.
• No finalising, no consecutive number range, no archive. A number drawn under GoBD and section 14 of the German VAT Act cannot be recalled; that does not belong in a tool triggered by a model. The invoice number is passed in, not drawn.
• No Peppol delivery. Peppol documents are produced, validated and read, including the SBDH transport envelope — but no access point is operated.
• No Word templates. The template route needs an additional licence.
• No PDF/A assurance. The hybrid PDF is produced, but without a PDF converter the visual layer carries no PDF/A-3 assurance. The answer says so through isPdfA and pdfAWarningCode.

Three things an assistant can get wrong

The tool descriptions name them explicitly, because all three concern statements about a user’s legal position.

1 · An undetected format is not a faulty invoice

If the format is not detected, there is no validation verdict. The field detected decides whether anything may be said about compliance at all. In the workstation tool, this very confusion once reported 88 out of 111 sample documents as “invalid”.

2 · Do not invent invoice data

A plausible-looking VAT ID, invoice number or an inferred date is a legal defect, not a matter of formatting. That is why creating is strict by default: a non-compliant result is not written but returned with the validation report.

3 · Pass on localOnly and isPdfA unchanged

“VIES was unreachable, only the format was checked” is something other than “the number is registered”. A document described as PDF/A that is not one would be worse than a missing label.