MCP Server

Enable AI assistants to generate invoices with the Model Context Protocol.

On This Page

🤖 What is MCP? 📦 Installation 🔧 Available Tools 💡 Usage Examples 🌐 Direct HTTP Access 🔍 Troubleshooting

What is MCP?

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools and data sources. Our MCP server allows Claude, GPT, and other AI assistants to generate and validate e-invoices directly through natural language.

Use Case: Enable Claude Code or other MCP clients to generate invoices from conversation. Example: "Generate an invoice for 10 hours of consulting at €150/hour from Acme GmbH to Customer AG"

Installation

Option 1: Claude Code (Recommended)

claude mcp add @thelawin/mcp-server

The MCP server will automatically connect and be available in your Claude Code sessions.

Option 2: Manual Configuration

Add to your MCP settings file (~/.config/claude/mcp_settings.json on macOS/Linux, %APPDATA%\claude\mcp_settings.json on Windows): 

{
  "mcpServers": {
    "thelawin": {
      "command": "npx",
      "args": ["@thelawin/mcp-server"],
      "env": {
        "THELAWIN_API_KEY": "env_sandbox_your_key_here"
      }
    }
  }
}
API Key: You can provide your API key via env config (as shown above) or pass it in each prompt. Get your key from the Dashboard.

Option 3: Direct HTTP (No Installation)

Use our HTTP endpoint at https://api.thelawin.dev/mcp directly with any MCP-compatible client (see Direct HTTP Access below).

Available Tools

The MCP server exposes three tools that AI assistants can call:

1. thelawin_generate

Generate a ZUGFeRD-compliant e-invoice from structured data. Returns PDF as Base64 string.

Parameter Type Required Description
api_key string Yes API key from Dashboard
format string No Output format: zugferd, facturx, xrechnung, peppol, etc. (default: auto)
template string No PDF template: minimal, standard, modern (default: standard)
locale string No Language: de-DE, en-US, fr-FR, etc. (default: auto)
invoice object Yes Invoice data (seller, buyer, items, etc.)

2. thelawin_validate

Validate invoice data before generation (dry-run). Returns validation results without creating PDF.

Parameter Type Required Description
api_key string Yes API key from Dashboard
invoice object Yes Invoice data to validate
Pro Tip: The thelawin_validate tool accepts the same parameters as thelawin_generate but doesn't consume credits. Use it to check for errors before generating invoices.

3. thelawin_retrieve

Extract structured invoice data from existing e-invoice documents (ZUGFeRD, Factur-X, XRechnung, Peppol, UBL, CII, FatturaPA). Returns JSON in the same format used by thelawin_generate.

Note: This is metadata extraction from e-invoices with embedded XML, not OCR. Plain PDFs without embedded XML are not supported.
Parameter Type Required Description
data_base64 string Yes Base64-encoded PDF or XML file content
content_type string Yes application/pdf, application/xml, or text/xml

Usage Examples

Natural Language Prompts (Claude Code)

Example 1: Simple Invoice

"Generate an invoice for 10 hours of consulting at €150/hour from Acme GmbH (Berlin) to Customer AG (Munich), due in 14 days. Use my API key: env_sandbox_xxx"

Example 2: Multiple Items

"Create a ZUGFeRD invoice from ACME Inc. (VAT: DE123456789) to XYZ Corp (VAT: FR98765432100) with 3 items: 100x Widget A at €10 each (19% tax), 50x Widget B at €25 each (19% tax), and 1x Shipping at €15 (7% tax)"

Example 3: Validation Only

"Validate this invoice data before generating: [invoice JSON]. Check for VAT format and currency errors."

Example 4: Specific Format

"Generate a Peppol BIS invoice from Norwegian company (VAT: NO123456789MVA) to UK company (VAT: GB123456789) for software license renewal (€1,200 + 25% VAT)"

Direct HTTP Access

You can also access MCP tools via HTTP without the npm package. Our API exposes a JSON-RPC 2.0 endpoint at /mcp: 

# List available tools
curl -X POST https://api.thelawin.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Call thelawin_generate
curl -X POST https://api.thelawin.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "thelawin_generate",
      "arguments": {
        "api_key": "env_sandbox_xxx",
        "format": "zugferd",
        "invoice": {
          "invoice_number": "2026-001",
          "issue_date": "2026-01-15",
          "due_date": "2026-02-14",
          "currency": "EUR",
          "seller": {
            "name": "Acme GmbH",
            "vat_id": "DE123456789",
            "address": "Hauptstr. 1, 10115 Berlin, Germany"
          },
          "buyer": {
            "name": "Customer AG",
            "vat_id": "DE987654321",
            "address": "Marienplatz 1, 80331 München, Germany"
          },
          "items": [
            {
              "name": "Consulting Services",
              "quantity": 10,
              "unit": "HUR",
              "unit_price": 150.00,
              "tax_rate": 19.0
            }
          ]
        }
      }
    }
  }'

Response format: 

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"pdf_base64\": \"JVBERi0xLjQK...\"}"
      }
    ]
  }
}

Troubleshooting

❌ MCP Server Not Connecting

Symptom: Claude Code shows "MCP server 'thelawin' not found"

Solutions:

  • Verify @thelawin/mcp-server is installed: npm list -g @thelawin/mcp-server
  • Check MCP settings file path: ~/.config/claude/mcp_settings.json
  • Restart Claude Code after configuration changes
  • Use Direct HTTP Access as fallback (see above)

❌ 401 Unauthorized in MCP Calls

Symptom: MCP tool returns "unauthorized" error

Solutions:

  • Provide API key in prompt: "Use my API key: env_sandbox_xxx"
  • Or set THELAWIN_API_KEY in env config (mcp_settings.json)
  • Get your key from Dashboard
  • Check key prefix: Sandbox keys start with env_sandbox_

❌ Invalid JSON-RPC Request

Symptom: HTTP endpoint returns {"error": "invalid_request"}

Solutions:

  • Include required fields: jsonrpc, id, method
  • Use tools/call method (not generate)
  • Wrap tool name in params.name field
  • See Direct HTTP Access examples above

❌ Invoice Validation Failed

Symptom: MCP tool returns validation errors

Solutions:

  • Use thelawin_validate tool first to check for errors
  • Check Error Codes documentation
  • Verify VAT ID format (e.g., DE123456789, not DE 123456789)
  • Use UN/ECE unit codes (see Units reference)
Learn More: Check the official MCP documentation for advanced configuration and custom client integration.