Skip to content

MCP server

The same engine is exposed to AI agents through the Model Context Protocol as a remote server (Streamable HTTP, stateless). An agent in Claude, Cursor, VS Code, ChatGPT or your own application can produce, check and read compliant e-invoices without you writing any integration code.

Endpoint: https://facturx.orvel.dev/mcp

Tools

Tool What it does Input Output
generate_invoice Invoice JSON to Factur-X PDF/A-3, CII XML or UBL XML invoice (object), profile, output, language, check, footer_text Text summary (totals, warnings) + the document as an embedded resource (base64 PDF or XML text)
embed_xml Attach a Factur-X XML to your own PDF pdf_base64, xml, check, language Summary + PDF/A-3 as embedded resource
validate_invoice XSD + EN 16931 schematron (+ French fr-ctc) document_base64 or xml, check Structured report: valid, profile, findings[] with rule ids
extract_invoice Read an e-invoice document_base64 or xml, include_xml fields (parties, totals, VAT, lines) and optionally the XML

Resources:

  • facturx://schema/invoice: JSON Schema of the invoice argument (agents read it to fill the object correctly).
  • facturx://guide/french-reform: one-page cheat sheet of the French reform.

All tools are annotated readOnlyHint / idempotentHint: nothing is stored server-side, calling twice is safe.

Access and billing

Two self-service options, no account to request:

With your plan key Through AgenticMarket
URL https://facturx.orvel.dev/mcp the URL shown by the marketplace
Auth header Authorization: Bearer <key> none (the marketplace proxies)
Price included in every plan, Free included (Pricing) $0.05 per successful tool call, from the marketplace balance
Counting one document per successful tools/call, same monthly quota as REST per call

initialize, tools/list, resources/* and failed calls are never counted. Over quota, the server answers a JSON-RPC error (HTTP 402) with the upgrade link; the agent surfaces it as-is.

Client setup

The snippets use the plan key. If you connect through AgenticMarket, use the marketplace URL and drop the header.

Custom connectors cannot send a header yet, so use mcp-remote in claude_desktop_config.json:

{
  "mcpServers": {
    "facturx": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://facturx.orvel.dev/mcp",
        "--header", "Authorization: Bearer ${FACTURX_KEY}"
      ],
      "env": { "FACTURX_KEY": "your-license-key" }
    }
  }
}

On Claude.ai (web) without a local process, connect through AgenticMarket instead.

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "facturx": {
      "url": "https://facturx.orvel.dev/mcp",
      "headers": { "Authorization": "Bearer your-license-key" }
    }
  }
}

.vscode/mcp.json:

{
  "servers": {
    "facturx": {
      "type": "http",
      "url": "https://facturx.orvel.dev/mcp",
      "headers": { "Authorization": "Bearer your-license-key" }
    }
  }
}

claude mcp add --transport http facturx https://facturx.orvel.dev/mcp \
  --header "Authorization: Bearer your-license-key"

from mcp import Client
from mcp.client.streamable_http import streamable_http_client

url = "https://facturx.orvel.dev/mcp"
headers = {"Authorization": "Bearer your-license-key"}
async with streamable_http_client(url, headers=headers) as (read, write, _):
    async with Client((read, write)) as client:
        result = await client.call_tool("validate_invoice", {"xml": xml_text, "check": "fr-ctc"})
        print(result.structured_content["valid"], result.structured_content["findings"])

Example prompts

  • "Generate a Factur-X invoice for this quote: seller Atelier Numérique SAS (SIREN 732829320, VAT FR40732829320, Paris), buyer Boulangerie Dupont (SIREN 552081317, Lyon), 1 x website development 2500 EUR HT at 20%, 12 months hosting at 15 EUR, due in 30 days."
  • "Validate the attached supplier invoice against the French rules and explain each failing rule in plain words."
  • "Extract the totals and VAT breakdown from these three PDFs and give me a table."

The tool descriptions tell the agent to use decimal strings for amounts, ISO dates, and to always run validate_invoice on files it did not generate, so you rarely need to say it.

Design notes for integrators

  • Stateless: no session, no cookies; each request is independent. Safe behind gateways and load balancers.
  • Payloads: documents travel base64-encoded inside JSON. A 300 KB PDF is about 400 KB of JSON; the server accepts up to 20 MB per request.
  • Errors are returned as tool errors with a readable message that includes the failing rule ids, so the agent can fix the input and retry.
  • generate_invoice refuses to return a file that does not pass the requested rule set. What you get is compliant, or you get the list of reasons.