English Français العربية

Invoice Intake (reference)

Official registry Finance and payments

Reference invoice-intake MCP servers: read/draft/commit split, typed errors, approval gate, audit

Source code Website Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

PYPI package invoice-intake-mcp
Claude Code 
claude mcp add invoice-intake-reference -- uvx invoice-intake-mcp==0.1.1 --role read
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "invoice-intake-reference": {
            "command": "uvx",
            "args": [
                "invoice-intake-mcp==0.1.1",
                "--role",
                "read"
            ]
        }
    }
}

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. invoice-intake-mcp
  2. What it shows
  3. Run it
  4. Use the servers from an MCP client
  5. Tests and evals
  6. Layout

invoice-intake-mcp

Reference implementation of the tool-design rules in Designing MCP servers and tools that agents can use safely, on a real back-office process: supplier invoice intake.

It is small on purpose. The fake ERP is a JSON file; everything else is the shape we use in production systems.

What it shows

RuleWhere
Model the business operation, not the APIerp_match_po, erp_stage_invoice, not PATCH /invoices
Separate reads, drafts and commits--role read server (reads + reversible staging) vs --role commit server (irreversible post)
Strict schemasLiteral enums for currency, ids not names, found=false as a valid empty result
Permissions on the server and credentialspecialist agents get read; only the orchestrator connects to commit
Tool results are untrusted inputinvoices_extract says so in its description; the eval set includes a prompt-injection case
Typed errors`{"error": "approval_required" \"validation_failed" \"business_rule" \"not_found", "retryable": bool, ...}`
Log for the auditoraudit.jsonl: actor, tool, ids, approval reference
Human checkpoint enforced server-sideerp_post_invoice refuses without a recorded approval, whatever the client believes

Run it

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"

python -m invoice_intake_mcp.orchestrator            # process the inbox
python -m invoice_intake_mcp.approve list            # see what is waiting
python -m invoice_intake_mcp.approve APR-xxxx approved --by cfo
python -m invoice_intake_mcp.orchestrator --resume   # post the approved item
cat audit.jsonl

Expected first run:

plan: 4 new invoices -> extract, resolve vendor, match, stage, post-or-approve
  invoice_2291.pdf: staged STG-… -> WAITING for APR-…        (7,420 EUR > 5,000 limit)
  invoice_2292.pdf: match=goods_not_received -> REVIEW
  invoice_2293.pdf: match=variance {"variance_pct": 2.34} -> REVIEW
  invoice_2294.pdf: no PO reference -> REVIEW (ask requester)

The orchestrator is deterministic so the flow replays without an API key. An LLM belongs in the places marked in orchestrator.py (ambiguous vendor candidates, free-text remarks, the note back to the requester), not in the match rule, the tolerance or the approval limit.

Use the servers from an MCP client

{
  "mcpServers": {
    "invoice-intake-read":   { "command": "uvx", "args": ["invoice-intake-mcp", "--role", "read"] },
    "invoice-intake-commit": { "command": "uvx", "args": ["invoice-intake-mcp", "--role", "commit"] }
  }
}

Give an agent only the read server unless it is the orchestrator.

Tests and evals

pytest                 # unit tests on the core operations and the gate
python evals/run.py    # replayable decision cases, run on every change

Layout

invoice_intake_mcp/
  core.py          business operations + policy (tolerance, approval limit), pure functions
  server.py        the two MCP servers and their tool descriptions
  orchestrator.py  minimal hub over MCP stdio: read server for work, commit server for posting
  approve.py       the human decision, as a CLI
  audit.py         append-only JSONL audit log
  erp.py           fake ERP / inbox state (JSON file)
tests/             pytest
evals/             cases.jsonl + run.py

MIT. Built by JustDukkan, AI solutions architecture.

Frequently asked questions

What is Invoice Intake (reference)?

Reference invoice-intake MCP servers: read/draft/commit split, typed errors, approval gate, audit

How do I install Invoice Intake (reference)?

It runs on your machine. In Claude Code: claude mcp add invoice-intake-reference -- uvx invoice-intake-mcp==0.1.1 --role read. For other clients, paste the JSON configuration from this page into their MCP settings.

Does Invoice Intake (reference) need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is Invoice Intake (reference) open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains Invoice Intake (reference)?

It is published by justdukkan. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.