# Invoice Intake (reference)

Reference MCP implementation for supplier invoice processing, featuring separated read and commit roles, server-side approval gates, and audit trails.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI
- Author: justdukkan
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/justdukkan/invoice-intake-mcp
- Updated: 2026-09-13
- HTML: https://affpapa.org/en/nevibecode/mcp/invoice-intake-reference

## What it does

This project provides a blueprint for structuring agent tools safely around back-office workflows. Instead of exposing low-level endpoints, tools model concrete domain events like purchase order matching and invoice staging. An internal JSON store serves as a mock ERP backend.

The system splits responsibilities via server arguments: `--role read` handles non-destructive steps, while `--role commit` reserves irreversible actions for the primary orchestrator. An enforced server guard blocks `erp_post_invoice` whenever a valid human sign-off reference is absent. Every executed tool call gets written to an append-only `audit.jsonl` ledger.

Execution relies on Python and `uvx`. Any attempt to post without explicit authorization fails immediately with an `approval_required` typed response.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add invoice-intake-mcp -- uvx invoice-intake-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from invoice-intake-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add invoice-intake-reference -- uvx invoice-intake-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from invoice-intake-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "invoice-intake-reference": {
            "command": "uvx",
            "args": [
                "invoice-intake-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from invoice-intake-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "invoice-intake-reference": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "invoice-intake-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from invoice-intake-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add invoice-intake-reference uvx invoice-intake-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from invoice-intake-mcp <command>

## When to use it
- Prevent agents from committing ledger entries without verified manager sign-off
- Isolate routine inspection tasks from irreversible database mutations
- Maintain a structured `audit.jsonl` log of every automated tool execution
- Handle data extraction failures and prompt injections using typed errors

## Example prompts
- Match pending supplier invoices against active purchase orders
- List staged invoice items that exceed the automatic authorization threshold
- Commit invoice posting once approval reference APR-2291 is granted

## Similar
- [invoice-generator](https://affpapa.org/en/nevibecode/skills/invoice-generator.md) — skill · 5100 installs
- [Invoice Automation](https://affpapa.org/en/nevibecode/skills/invoice-automation.md) — skill · 4700 installs
- [invoice-aging](https://affpapa.org/en/nevibecode/skills/invoice-aging.md) — skill · 449 installs
- [Document to JSON – PDF Invoice/Statement/Contract Parser](https://affpapa.org/en/nevibecode/mcp/document-to-json-pdf-invoicestatementcontract-parser.md) — MCP server · ★ 8
- [netsuite-suitescript-records-reference](https://affpapa.org/en/nevibecode/skills/netsuite-suitescript-records-reference.md) — skill · 1000 installs
- [footnote](https://affpapa.org/en/nevibecode/mcp/footnote.md) — MCP server

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md