Henrri (unofficial)

Important

This is not an official Henrri product. It is an independent, open-source project, not made, endorsed or supported by Henrri. It covers the published Henrri v1 specification operation by operation, as faithfully as the API allows, and documents where the API behaves differently from its documentation. See Disclaimer.

Ask your assistant "invoice Atelier Martin for three days of development at 600 € excl. tax", "who still owes me money?", "turn the signed quote D-26-11-3 into an invoice" — and get it done in the same Henrri your accountant reads.

> who still owes me money?

  list_payment_milestones   is_overdue = true · 7 milestones
                            ATELIER MARTIN    I-26-10-12   1 440,00 €   23 days late
                            LOVELACE          I-26-10-17     864,00 €    9 days late
                            …
                            overdue total     4 812,40 €

> invoice Atelier Martin for 3 days of development at 600 € excl. tax

  create_document           draft invoice 9632 for ATELIER MARTIN
  add_document_line         3 × Journée de développement · 600,00 € · VAT 20 %
  get_document_with_all     1 800,00 € excl. tax · 360,00 € VAT · 2 160,00 € incl. tax
                            finalize it? It locks the invoice for good and costs 8 credits.

Why

Henrri's API is a clean REST surface, but handed raw to a language model it goes wrong in predictable ways: a PUT erases every field it is not sent, a document is a draft until a call that can never be undone, finalizing costs credits, the monthly quota and the rate limiter both answer 429, and a model cannot tell a document's id from its number.

• The whole API, nothing hidden. All 87 operations of the v1 specification: 85 routes, one tool each, and the two authentication routes driven by the client itself. A test checks the tool table against spec/operations.tsv, and CI checks that file against the live production and sandbox specifications every day.
• Updates that update. Every update_* tool takes only what changes, reads the resource, merges, and writes back what Henrri accepts — no more customers losing their comment because their website changed.
• Fail-closed where it cannot be undone. finalize_document, validate_quotation, the pay tools, cancel_deposit and every delete refuse to run without confirm: true, and the refusal states what would happen: the document, its total, its customer, the credits. HENRRI_READ_ONLY=1 withholds every write tool.
• Errors a model can act on. Failures come back as tool results with isError: true and Henrri's RFC 9457 problem document: the stable errorCode (ALREADY_FINALIZED, LINES_MISSING, QUOTA_EXCEEDED…), the detail, the invalid fields, and the traceId for Henrri's support, plus a hint when the fix is not obvious.
• The API's manners, handled once. Ten-minute tokens renewed ahead of expiry; the rate limiter, 503 and busy finalizations retried; the credit quota never retried; a POST never resent after it may have run; list filters sent as repeated keys; periods such as last month turned into Henrri's inclusive dates.
• Webhooks, verified. Over HTTP the server receives Henrri's deliveries at /webhooks, checks their HMAC-SHA256 signature in constant time, refuses replays, and lets the model read what happened.
• Written for a model to read. Structured output with schemas on all 89 tools, annotations on every one, four prompts that stop and ask before anything irreversible, and server instructions that say up front: ids not numbers, euros, drafts versus finalized.

Install

# macOS on Apple silicon; swap the target for x86_64-apple-darwin,
# x86_64-unknown-linux-gnu or aarch64-unknown-linux-gnu
V=v0.1.0 T=aarch64-apple-darwin
curl -LO https://github.com/edouard-claude/henrri-mcp/releases/download/$V/mcp-henrri-$V-$T.tar.gz
tar xzf mcp-henrri-$V-$T.tar.gz
sudo mv mcp-henrri-$V-$T/mcp-henrri /usr/local/bin/

git clone https://github.com/edouard-claude/henrri-mcp
cd henrri-mcp
cargo build --release
# the binary is at target/release/mcp-henrri

cargo install --git https://github.com/edouard-claude/henrri-mcp

docker run --rm -i \
  -e HENRRI_USERNAME -e HENRRI_PASSWORD \
  ghcr.io/edouard-claude/henrri-mcp:latest

Get API access

Henrri gives API access with its developer offer. There are two environments, with separate accounts:

Three ways to authenticate, in this order of precedence:

1. A developer client — HENRRI_CLIENT_ID and HENRRI_CLIENT_SECRET, exchanged at POST /v1/users/authenticate and renewed through POST /v1/users/refresh-token.
2. An API user — HENRRI_USERNAME and HENRRI_PASSWORD, the OAuth2 password grant on POST /v1/users/token (this is what the sandbox hands out, e.g. [email protected]).
3. A ready-made token — HENRRI_ACCESS_TOKEN, used as is and never renewed (ten minutes).

Then check everything works:

HENRRI_ENVIRONMENT=sandbox HENRRI_USERNAME=… HENRRI_PASSWORD=… mcp-henrri --check

environment  sandbox
base url     https://api-sandbox.henrri.io
credentials  API user (OAuth2 password grant)
toolsets     account, customers, documents, catalog, payments, revenues, webhooks
tools        89
token        ok
hello world  "Hello World"
user         [email protected] (16079), role admin
company      My company (947), plan discovery
credits      used 100 of unlimited, unlimited left

ready.

Configure

Everything is read from the environment, once, at startup. A missing or malformed variable stops the process with a message naming it.

Copy .env.example to .env for local work; it is git-ignored.

Connect a client

{
  "mcpServers": {
    "henrri": {
      "command": "/usr/local/bin/mcp-henrri",
      "env": {
        "HENRRI_USERNAME": "[email protected]",
        "HENRRI_PASSWORD": "…",
        "HENRRI_ENVIRONMENT": "production"
      }
    }
  }
}

claude mcp add henrri \
  -e [email protected] -e HENRRI_PASSWORD=… \
  -- /usr/local/bin/mcp-henrri

{
  "servers": {
    "henrri": {
      "type": "stdio",
      "command": "/usr/local/bin/mcp-henrri",
      "env": { "HENRRI_USERNAME": "[email protected]", "HENRRI_PASSWORD": "…" }
    }
  }
}

Tip: a bookkeeper who only reads can run with HENRRI_READ_ONLY=1; an assistant that only chases payments can run with HENRRI_TOOLSETS=customers,payments.

Tools

89 tools in seven toolsets. mcp-henrri --list-tools prints the ones your configuration exposes. R reads, W writes, D is destructive or irreversible and needs confirm: true (so do the two pay tools and validate_quotation).

documents — quotes, invoices, credit notes, lines, PDFs

payments — milestones, deposits, payments

customers — customers and contacts

catalog — items, categories, text items, units

account, revenues and webhooks

POST /v1/users/authenticate and POST /v1/users/refresh-token are not tools: the client calls them itself, as does the OAuth2 token endpoint, POST /v1/users/token.

Resources and prompts

Henrri, as it actually behaves

Found against the sandbox while building this server, and handled so the model never meets them. The tests in tests/api_contract.rs pin each one.

• A PUT erases what it is not sent. Updating a customer's website without its comment deletes the comment. Update tools read, merge and write back.
• Some fields read back as "" and are refused as "". vatNumber, siret… An unchanged empty string is left out of the write.
• A customer PUT carrying contacts is refused (PUT_WITH_CUSTOMER); a line PUT carrying its nested item, its type or its computed totals is refused too. They are dropped.
• A body-less POST without Content-Length gets an IIS 411. transform-to-invoice, deposit-request, pdf/url… carry an explicit empty body.
• A comma-separated list filter is not an error, it is an empty page (the documentation says 400). Lists are sent as repeated keys.
• The due date is ignored when a milestone is created, and honoured when it is updated: create_payment_milestone sets it in a second call.
• confirmFirstOfMonth is refused in the finalize body although the FIRST_ACCOUNTING_DOCUMENT_MONTH error asks for it: it is sent as a query parameter.
• A new unit is answered with id: 0: create_unit finds it by its name.
• The company-wide milestone lists only show finalized documents, and a finalized document points at a frozen copy of its customer (parentCustomerId): a draft's schedule is read through the document, a customer's through the copy.
• The city follows the postal code. Henrri rewrites it ("Paris 01"); a city that does not match the code is blanked. Change both together.
• refresh_token is refused on /v1/users/token; an API user is simply granted again.
• Two different 429s. The per-minute rate limiter is retried; QUOTA_EXCEEDED (the monthly credits) is not.
• PDF rendering is slow, and broken on the sandbox at the time of writing (500 or no answer); the PDF routes get their own, longer timeout.

Safety

• Irreversible calls are fail-closed: without confirm: true nothing leaves the process, and the refusal says what would happen. The server instructions and the prompts tell the model to show the person and get a yes first.
• HENRRI_READ_ONLY=1 registers no write tool at all: read-only is decided by each tool's readOnlyHint, not by a list that could drift.
• Secrets never reach a log or a Debug output; logs go to stderr.
• PDFs are written only inside HENRRI_DOWNLOAD_DIR, under a sanitized file name.
• Over HTTP, /mcp requires HENRRI_HTTP_TOKEN (compared in constant time) and the server refuses to listen off loopback without one; on loopback, Host is validated against DNS rebinding.
• Webhook deliveries are accepted only with a valid signature, a timestamp within five minutes, and once per delivery id.

Run it over HTTP

HENRRI_HTTP_TOKEN=$(openssl rand -hex 32) \
HENRRI_WEBHOOK_SECRET=… \
mcp-henrri --http 127.0.0.1:8080
# MCP at http://127.0.0.1:8080/mcp, webhooks at /webhooks, health at /healthz

The Streamable HTTP transport serves many sessions, which share one Henrri token and one webhook inbox. Behind a reverse proxy, bind 0.0.0.0 (a token is then mandatory) and point Henrri's webhook callback at https://<your-host>/webhooks. Henrri sends each delivery once, with no retry: the receiver answers 204 immediately, duplicates included.

Verify

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test                      # unit, contract (fake Henrri), stdio and HTTP protocol tests

Against the real sandbox, with your sandbox credentials in .env (it builds a draft quote and deletes it; nothing is finalized):

set -a; source .env; set +a
HENRRI_SANDBOX_TESTS=1 cargo test --test sandbox

Has the API moved? This prints the live operations, in the format of spec/operations.tsv (CI runs it daily against production and sandbox):

scripts/spec-operations.sh | diff - spec/operations.tsv

Releasing

Bump version in Cargo.toml and server.json, add a CHANGELOG.md section, then push a vX.Y.Z tag. The release workflow checks the three agree, builds binaries for five targets, publishes the multi-arch image to GHCR and the release notes from the changelog.

Contributing

Issues and pull requests are welcome. Keep the rule the code follows: one route, one tool, and a test for every behaviour the real API forces on it. See CONTRIBUTING.md.

Disclaimer

Henrri is a trademark of its owner. This project is unofficial: it is not affiliated with, endorsed by or supported by Henrri. It is built from Henrri's public v1 API specification and tested against Henrri's sandbox; behaviour may change when the API does. Finalizing documents in production has fiscal consequences and costs API credits: you remain responsible for what is issued in your name. Provided under the MIT license, without warranty.

License

MIT © 2026 Edouard Claude