InvoiceXML MCP server

InvoiceXML MCP Server

A Model Context Protocol server that exposes the InvoiceXML API to AI agents. Covers Factur-X, ZUGFeRD, XRechnung, UBL / CII, and Peppol BIS Billing 3.0.

The same codebase runs in two deployment shapes, selected at startup by one environment variable:

Both run the same binary; only the configuration differs. The repository is platform-independent — it knows nothing about where or how you host it.

Architecture

+----------------------+   ProjectReference   +----------------------+
|  InvoiceXml.Mcp.Core | -------------------> |  InvoiceXml.Mcp.Host |
|  (SDK: client+tools) |                      |  (the deployable)    |
+----------------------+                      +----------------------+

InvoiceXml.Mcp.Core is a small, transport-agnostic SDK:

• IInvoiceXmlClient — typed client over the public REST API
• HttpInvoiceXmlClient — the only implementation; consumes an HttpClient from IHttpClientFactory
• InvoiceXmlClientOptions — base URL, timeout (no auth)
• AddInvoiceXmlMcpCore(IServiceCollection, IConfiguration) — DI entry point; returns the IHttpClientBuilder so the host attaches auth as a DelegatingHandler

The SDK never sees credentials. The host applies them through the HTTP pipeline. That seam is what lets one codebase serve both deployment modes.

InvoiceXml.Mcp.Host is an ASP.NET Core 10 app:

• Reads Mcp:AuthMode (ApiKey or OAuth) at startup
• Wires the matching DelegatingHandler onto the Core HTTP client via AddHostAuth(...)
• Serves the MCP endpoint at POST /, a human-friendly welcome page at GET /, and /health

Adding a new auth mode = one arm in AuthExtensions.cs plus a small folder under Auth//. Adding a new tool = one [McpServerTool] class. Nothing else changes.

Repository layout

invoicexml-mcp/
├── src/
│   ├── InvoiceXml.Mcp.Core/              # the SDK: client, models, tools
│   │   ├── Enums/  Interfaces/  Models/  Options/  Services/  Tools/  Extensions/
│   └── InvoiceXml.Mcp.Host/              # the deployable host
│       ├── Auth/{ApiKey,OAuth}/          # the two auth modes
│       ├── Configuration/
│       ├── Program.cs
│       └── appsettings.json              # safe defaults, no secrets
├── tests/
│   ├── InvoiceXml.Mcp.Core.Tests/
│   └── InvoiceXml.Mcp.Host.Tests/
├── Directory.Build.props                 # repo-wide MSBuild defaults
├── Directory.Packages.props              # Central Package Management
├── global.json                           # pins the .NET SDK
└── InvoiceXml.Mcp.slnx

Running locally

You need a .NET 10 SDK and an InvoiceXML API key.

# 1. Provide your API key (pick one):

# A. dotnet user-secrets (recommended — kept outside the repo)
dotnet user-secrets --project src/InvoiceXml.Mcp.Host set "Mcp:ApiKey:Value" "your-key"

# B. environment variable
$env:INVOICEXML_API_KEY = "your-key"

# 2. Run
dotnet run --project src/InvoiceXml.Mcp.Host

GET http://localhost:5004/ shows a welcome page in a browser; the MCP endpoint is POST http://localhost:5004/; GET /health returns { "status": "ok" }.

Configuration

{
  // Required in OAuth mode. The public origin where this MCP server is reachable.
  // Used in the protected-resource metadata response.
  "McpUri": "https://mcp.example.com",

  "InvoiceXml": {
    "BaseUrl": "https://api.invoicexml.com",   // override for staging / local
    "Timeout": "00:01:40"
  },

Shortened. The full README is on GitHub.