jithox-mcp

# Jithox MCP — check a payment before your AI agent makes it

Jithox runs a remote [MCP](https://modelcontextprotocol.io) server. Its front
door is `preflight_payment`: one free call, before an agent pays an invoice,
that answers `stop`, `review_required` or `no_blockers_found` with signed
evidence. Next to it are read-only checks for e-invoices and payments: IBAN
structure, supplier bank-detail changes, Peppol BIS Billing 3.0 rule
validation, Peppol participant (receiver) lookup, and VIES lookup.

It is for developers and AI agents that prepare an e-invoice or a payment and
want a check **before** something is sent, submitted to Peppol, or paid.

This repository holds examples, a registry manifest and one agent plugin
package. It contains no server code. The server itself is hosted by Jithox.

## Install

```text
Remote MCP URL: https://jithox.com/api/mcp
Claude Code: claude mcp add --transport http jithox https://jithox.com/api/mcp
Codex: codex mcp add jithox --url https://jithox.com/api/mcp
Cursor: cursor://anysphere.cursor-deeplink/mcp/install?name=jithox&config=eyJ1cmwiOiJodHRwczovL2ppdGhveC5jb20vYXBpL21jcCJ9
VS Code: vscode:mcp/install?%7B%22name%22%3A%22jithox%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fjithox.com%2Fapi%2Fmcp%22%7D
Gemini CLI (~/.gemini/settings.json): {"mcpServers":{"jithox":{"httpUrl":"https://jithox.com/api/mcp"}}}
```

## Agent package

See [PACKAGE.md](PACKAGE.md) for the portable Agent Plugins package and its
Claude Code, Cursor, Gemini and Grok configuration. Validation scope and
primary sources are in [docs/PLUGIN_VALIDATION.md](docs/PLUGIN_VALIDATION.md).
No public directory listing or recommendation is implied.

After the reviewed package reaches the public default branch, Claude Code
can discover this repository marketplace with:

```text
/plugin marketplace add victor-emmanuel-c/jithox-mcp
/plugin install jithox@jithox
```

For Agent-Skills-compatible clients:

```bash
npx skills add victor-emmanuel-c/jithox-mcp
```

The v1.0.0 discovery-only check `DISABLE_TELEMETRY=1 npx skills add . --list`
listed one skill on 2026-10-02. The GEBRUIK1 candidate contains five skills;
that file inventory is not an installation or completed agent task. The remote command installs from the published repo;
review its permissions and selected version before accepting.

Build the upload ZIP deterministically from the repository root:

```bash
python scripts/plugin_package.py ../directories/jithox-agent-plugin-1.0.0.zip
```

The builder includes only its explicit runtime-file allowlist. ZIP uploads,
publisher verification and directory applications remain owner actions.

## Wat je je agent kunt vragen

| Natuurlijke vraag | Skill / commandnaam | Gratis/betaald | Eerlijke uitkomst |
|---|---|---|---|
| "Controleer deze factuur en betaalrun voordat ik betaal; meld wat niet gecontroleerd is." | `pay-invoices-safely` | Basischecks gratis; VAT/volledige review betaald na prijs en toestemming | Bevindingen en openstaande controles; geen betaling of betaaltoestemming. |
| "Het leveranciers-IBAN is gewijzigd; vergelijk het met onze administratie." | `verify-bank-detail-change` | Gratis | stop, verify_first of no_change; terugbellen via eigen administratie, geen recordwijziging. |
| "Bereid deze e-factuur Peppol voor en controleer de ontvanger." | `send-peppol-invoice` | Gratis | Regelbevindingen en documentondersteuning; geen verzending, acceptatie- of leveringsgarantie. |
| "Controleer dit betaalvoorstel voordat mijn agent geld uitgeeft." | `agent-payment-preflight` | Gratis | Echte preflight en beperkingen; onbekend is geen pass, er wordt niets betaald. |
| "Controleer deze btw-lijst of zoek dit bedrijf op; wat kost het?" | `check-vat-numbers` | Betaald; actuele kosten eerst uit live tools/list | Toestemming vóór de call; zonder toegang not_run en de live verbindingsstap, geen verzonnen registerantwoord. |

Gebruik gewone vragen voor skillselectie; activatie verschilt per client en is
nog geen bewezen taak. Expliciet: Claude `/jithox:<commandnaam>` (pluginnamespace),
Gemini `/<commandnaam>` (bij naamconflict kan de extensionnamespace verschijnen).
De bestanden staan in `commands/*.md` en `commands/*.toml`; alle vijf skills
hebben precies twee scenario's in hun eigen `references/examples.md`.
Zie [GEBRUIK1-validatie](docs/PLUGIN_VALIDATION.md) en het
[reproduceerbare evalpakket](eval/gebruik1/README.md). Eigen probes zijn geen
extern gebruik. Deze kandidaat is niet gepubliceerd of als beter geëvalueerd.

## Before your agent pays: `preflight_payment`

Call `preflight_payment` once, before your agent pays an invoice. It compares
what the person approved, as your agent reports it (payee, amount, currency,
account), with what is about to be paid; checks the IBAN and a changed
supplier bank account against the one on file; and answers `stop`,
`review_required` or `no_blockers_found`, with every check, what it does not
prove, and a signed evidence token. No account, no token. It never pays and
never calls an account safe: a check that did not run is listed as `not_run`,
never as a pass.

The 2026-09-25 measurement covered only `invoice_bank`; the other rails then
returned `review_required` with `rail_not_covered`. This is historical evidence,
not current coverage: read the live schema and every returned check for the
actual `invoice_bank`, `x402`, `card_or_giftcard` or `crypto_bridge` proposal.

The person approved paying invoice 2026-105 to Acme BV; the invoice now asks
for a different account than the one on file. The payment instruction is copied
from that invoice, so instructionSource is ingested_content, while approved
separately records what the person approved. These are fictional sample inputs:

```bash
curl -s https://jithox.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"preflight_payment","arguments":{"rail":"invoice_bank","approved":{"amount":"1210.00","currency":"EUR","payee":{"name":"Acme BV"},"purpose":"Invoice 2026-105"},"instructionSource":"ingested_content","payment":{"iban":"BE71 0961 2345 6769","amount":"1210.00","currency":"EUR","payeeName":"Acme BV","supplierCountry":"BE"},"ibanOnFile":"BE68539007547034"}}}'
```

The corrected request above was measured anonymously on 2026-10-03 with
`x-jithox-probe: gebruik1-fix`: HTTP 200, `review_required`, `instruction: warn`,
reasons `instruction_not_from_human` and `payment_change_verify_first`, and
`charged: false`. Missing invoice/VAT checks remained `not_run`. No payment
was made; the human approval did not change the invoice instruction's source.

Historical output from the old, incorrectly human-labelled request, measured on
2026-09-25; not the response to the corrected request above. The unwrapped
result is retained unchanged; `…` marks where it was shortened for this page:

```json
{
  "kind": "payment_preflight",
  "data": {
    "schemaVersion": "jx.payment-preflight/v1",
    "verdict": "review_required",
    "reasons": [{ "code": "payment_change_verify_first", "check": "payment_change" }],
    "humanStep": "Call the supplier back on a phone number from your own records (never one from this invoice or its e-mail) and have them read the account number to you.",
    "checks": [
      { "id": "approval", "status": "pass", … },
      { "id": "iban", "status": "pass", "value": "BE71 **** **** 6769: structure and check digits are right", … },
      { "id": "payment_change", "status": "warn", "value": "verify_first", "findings": ["bank_changed"], … },
      { "id": "vat_register", "status": "not_run", "reason": "needs_connection", … },
      …
    ],
    "billing": { "charged": false, "units": [] },
    …
  },
  "evidence": {
    "format": "compact-jws",
    "jws": "eyJhbG…",
    "jwks": "https://jithox.com/.well-known/jwks.json",
    "verify": "https://jithox.com/api/v1/evidence/verify",
    …
  }
}
```

Anyone can check that a verdict was not changed: `POST` the `jws` (optionally
with the `input` and its `inputSalt`) to
`https://jithox.com/api/v1/evidence/verify`. The untouched token answered
`"status": "valid"`; the same token with its verdict changed answered
`"invalid"` with reason `signature_mismatch` (tested 2026-09-25).

## Connect

```
https://jithox.com/api/mcp
```

Transport: Streamable HTTP (`POST`, JSON-RPC 2.0).
No account or token is needed for `tools/list`.

```json
{
  "mcpServers": {
    "jithox": { "url": "https://jithox.com/api/mcp" }
  }
}
```

### Claude Desktop

Open Settings → Developer → Edit Config, and add the block above to
`claude_desktop_config.json` (macOS:
`~/Library/Application Support/Claude/claude_desktop_config.json`; Windows:
`%APPDATA%\Claude\claude_desktop_config.json`). Restart Claude Desktop.

## Current tools

Use `tools/list` on this endpoint as the source for current availability:
tool names, descriptions and input schemas. Read that live response rather
than relying on a fixed tool count or catalog in this README.

**Limits:** 30 requests per minute per IP on this endpoint; above that you get
HTTP `429` with `Retry-After`.

## Peppol calls, run against production on 2026-09-23

Output is shown as returned; `…` marks where it was shortened for this page.

### 1. Will Peppol accept this invoice?

```bash
curl -s https://jithox.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_peppol_ready","arguments":{"invoiceNumber":"INV-2026-0001","issueDate":"2026-09-23","currency":"EUR","buyerReference":"PO-4471","totalWithoutVat":1000,"totalVat":210,"totalWithVat":1210,"lines":[{"description":"Consulting hours","quantity":10,"unitPrice":100,"vatPercent":21}],"supplier":{"name":"Seller BV","countryCode":"BE","endpointId":"0403170701","endpointScheme":"0208"},"customer":{"name":"Buyer NV","countryCode":"BE","endpointId":"0400378485","endpointS