io.github.herve-coulon/tax-retirement

Qotien — French Tax & Retirement MCP

A sourced, dated calculation API for French personal taxation and retirement, exposed over MCP. Every response carries a confidence level, its legal sources, and the fiscal year — the engine never guesses a fact.

Hosted remote server, paid per call via x402 (USDC on Base). Capabilities that return a fact are billed from the first call; two discovery tools are free. No account, no API key to store, no personal data — inputs are abstract numbers (income, parts, pension points), never stored.

Connect

Add it to any MCP client that supports a remote Streamable HTTP server, pointing at the endpoint above. Call qotien_capacites first (free) for the machine-readable catalog of tools, confidence levels, and prices.

Why call this instead of computing it yourself

A general LLM (or a code interpreter) can do arithmetic, but it does not reliably know the current, exact French rules — the 2026 income-tax brackets and décote thresholds, the value of an Agirc-Arrco or CARMF pension point, the reversion rate of each fund, which tax-reduction rates are in force this year. It will produce a confident, wrong number. Qotien is up to date, sourced, and re-verified against primary sources at every release — the value where a tax or pension error is unacceptable (fintech, insurtech, advisory tools, wealth-management software).

Two rules the engine never breaks:

• A figure never travels alone — every fact comes with its fiscal year, its legal sources, and a confidence level.
• A calculation, not a guess — when a rule or input is missing, the tool returns non_calculable (an honest refusal), never an invented number and never an "average" rate.

Tools — 4 domains, 38 tools

MCP tool names are prefixed by domain (fiscal_*, retraite_*, simulateurs_*, referentiel_*); the same capabilities are reachable over REST under their bare names (tmi, per_gain, …). Each tool's tier is shown as [protocole] (free) · [barème] · [étude] · [optimiseur] (see Pricing).

Fiscal (income tax & wealth) — deterministic, confiance: fiable

• fiscal_impot_revenu [barème] — income tax (progressive brackets, family quotient, décote)
• fiscal_tmi [barème] — marginal tax rate
• fiscal_cehr [barème] — exceptional contribution on high incomes (optional rfr_n1 / rfr_n2 apply the exceptional-income smoothing of art. 223 sexies II-1)
• fiscal_prelevements_sociaux [barème] — social-levy rate by income type (17.2 % vs 18.6 %)
• fiscal_surtaxe_pv_immobiliere [barème] — real-estate capital-gains surtax
• fiscal_per_plafond [barème] — PER deduction ceiling (N-1 PASS for employees, N for self-employed)
• fiscal_plus_value_immobiliere [étude] — real-estate capital gain (holding-period abatements; acquisition_gratuite for inherited or gifted property: actual costs only, no 7.5 % flat allowance; quote_part + valeur_pleine_propriete apply the €15,000 exemption per co-owned or dismembered share in full ownership; terrain for land: no 15 % works allowance)
• fiscal_ifi [étude] — real-estate wealth tax (main residence −30 %; optional 75 % income cap, art. 979, computed on gross income: dividends before the 40 % allowance, flat-tax income included)
• fiscal_foncier_regime [étude] — unfurnished rental: micro-foncier vs actual-expense regime (household tax Δ)
• fiscal_lmnp_regime [étude] — furnished rental (LMNP): micro-BIC vs actual regime with depreciation (household tax Δ)
• fiscal_succession [étude] — inheritance duties per child (art. 777) and estimated saving of an early donation
• fiscal_cdhr [étude] — differential contribution on high incomes (20 % floor + décote)
• fiscal_per_gain [étude] — tax saved by a PER contribution: the total Δ (brackets + CEHR/CDHR), never "contribution × marginal rate"
• fiscal_niches_plafond [étude] — tax-reduction cap (art. 200-0 A) on reductions, with the excluded items handled (donations: 20 % limit on the total, Coluche €2,000 bracket outside it; JEI/JEIR: subscription ceilings by situation, 40 % rate for impact companies via variante: "impact", shared €50,000 cap for 2024-2028 via jei_reductions_anterieures)
• fiscal_flat_tax_vs_bareme [étude] — PFU vs progressive-scale comparison
• fiscal_jeanbrun [étude] — Jeanbrun rental-investment depreciation (art. 31 I-1° i/j CGI); pass loyers_annuels, charges_annuelles, interets_annuels for the real saving (social levies only cut down to a zero net rental income, excess = global-income deficit capped at €10,700), otherwise a flagged theoretical maximum (hypothese_economie)

Retirement — variable confidence, never a bare figure

• retraite_ps_pension [barème] (fiable) — pension gross→net (CSG/CRDS/CASA + 1 % health on the complementary part)
• retraite_regimes [barème] (fiable) — discovery: the computable schemes (32 covered)
• retraite_surcote_parentale [barème] (estime) — parental surcote (+1.25 %/qtr, max 5 %)
• retraite_pension_regime [étude] (fiable) — pension of one points-based scheme, with a plausibility guard
• retraite_pension_annuites [étude] (fiable) — pension of an annuity-based scheme (public sector, special schemes)
• retraite_pension_totale [étude] (fiable) — consolidated multi-scheme pension (the full career statement in one call), gross→net
• retraite_estimation [étude] (estime/partiel/non_calculable) — approximate pension from partial data, with a range
• retraite_rachat [étude] (fiable) — trimester buyback (VPLR): cost, net-of-tax, gain, ROI
• retraite_progressive [étude] (estime) — phased retirement (pension fraction + part-time)
• retraite_optimisation [optimiseur] (estime) — ranked menu of end-of-career levers (buyback, parental surcote, phased retirement, optimal age, cumul, SAM, PER) with gain/ROI/confidence

Simulateurs (wealth projections) — confiance: estime

• simulateurs_girardin [barème] · simulateurs_rente_viagere [barème]
• simulateurs_scpi · simulateurs_scpi_credit · simulateurs_demembrement_scpi · simulateurs_apport_credit · simulateurs_rentabilite_reelle · simulateurs_private_equity — all [étude]

Référentiel (cite a dated fact) — confiance: sourcee

• referentiel_valeur [barème] — one reference value, with its primary source, legal basis, and verification date
• referentiel_recherche [barème] — search the reference by domain/keyword
• referentiel_versions [protocole] — reference version + freshness (free)

Meta

• qotien_capacites [protocole] — the catalog of tools, confidence levels, and prices (free; call this first)

Response contract

{
  "ok": true,
  "domaine": "retraite",
  "capability": "pension_regime",
  "confiance": "fiable",
  "result": { "...": "..." },
  "sources": ["references_officielles.json", "retraite_registre.js", "..."],
  "millesime_fiscal": "2026",
  "avertissement": "Deterministic indicative result — not personalized advice (CIF/DDA)."
}

• confiance: fiable (deterministic, golden-tested) · estime/partiel (approximation, with a range) · sourcee (dated reference fact) · non_calculable (honest refusal instead of a made-up number).
• A pension or a tax figure is never returned bare — confidence and sources travel with it.

Pricing — x402

Settlement in USDC on Base (eip155:8453). Prices are per successful call; a call that fails validation is not billed (settlement happens only on delivery).

An unpaid call gets HTTP 402 (x402 v2) on REST and MCP. On MCP the body carries both the x402 accepts field and a JSON-RPC -32002 error; a client that cannot pay sees a transport error (the call did not run). No anonymous free tier — to evaluate before paying, request a named trial key (header X-Qotien-Trial, issued manually). A euro-denominated commercial licence exists for application use (classic invoicing) — contact@qotien.fr.

Quick start

# List tools (free)
curl -s -X POST https://app.qotien.fr/api/fiscal/v1/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Catalog + prices (free)
curl -s -X POST https://app.qotien.fr/api/fiscal/v1/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"qotien_capacites","arguments":{}}}'

# A paid call (étude, $0.25) returns HTTP 402 with x402 payment instructions until settled.
curl -s -X POST https://app.qotien.fr/api/fiscal/v1/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"retraite_pension_regime","arguments":{"code_regime":"agirc_arrco","points":750.07}}}'

# Same call with a named trial key (evaluation, no payment): add the X-Qotien-Trial header.
curl -s -X POST https://app.qotien.fr/api/fiscal/v1/mcp \
  -H 'content-type: application/json' -H 'X-Qotien-Trial: <your-trial-key>' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"retraite_pension_regime","arguments":{"code_regime":"agirc_arrco","points":750.07}}}'
# → Agirc-Arrco, 750.07 points × €1.4386 (2026 service value) = €1,079/year gross (€90/month);
#   confiance: fiable · sources attached · referentiel v0.8.6 · millesime_fiscal 2026

An x402-capable client (or the x402-fetch / @x402/* libraries) handles the 402 → sign → settle → retry loop automatically.

Protocol

MCP 2025-06-18. Methods: initialize, tools/list, tools/call, ping. Transport: JSON-RPC 2.0 over HTTP POST; the endpoint also serves a keepalive SSE stream on GET (Accept: text/event-stream) for clients that open the server→client channel. Payment: x402 v2 (EIP-3009 transferWithAuthorization, USDC on Base); verification and settlement go through the Coinbase CDP x402 facilitator (api.cdp.coinbase.com), called server-side by app.qotien.fr.

License

Code in this repository: MIT (see LICENSE). Reference data returned by the API: CC BY 4.0 — cite “Qotien — qotien.fr”.

Disclaimer

Results are deterministic indicative computations based on the French tax & social-security reference for the stated fiscal year. They are the raw output of a calculation engine and do not constitute personalized financial advice within the meaning of French CIF/DDA regulation.

Part of Qotien — the reference for French personal-finance data: aggregated, sourced, dated, re-verified every year. Human-readable (qotien.fr/sources) and machine-readable (this MCP). Reference data under CC BY 4.0 — cite “Qotien — qotien.fr”.