AI Agent Integration

Clearvo MCP Server

The Clearvo MCP server lets Claude Code, Cursor, Windsurf, and any MCP-compatible AI tool submit invoices to tax authorities, calculate tax, validate business tax numbers, and manage entities — without writing a line of integration code.

What you can do in 60 seconds — Once set up, ask Claude:

“Submit an invoice for €5,000 to Acme SpA in Italy”
“Calculate VAT for a B2B sale from Germany to France”
“Validate this UK VAT number: GB123456789”
“Create a new entity for our Irish subsidiary”

Set up now →

Quick setup

1

Get a free API key

Create a free account at app.clearvo.io. Your API key is issued immediately — no sales call, no waiting. Use a csk_test_... sandbox key for development.

2

Add to your AI tool

Select your editor below — the server runs via npx, no global install needed:

Run this command once in your terminal. The --scope user flag registers the server globally across all projects.

Terminal

claude mcp add --scope user clearvo -e CLEARVO_API_KEY=csk_live_... -e CLEARVO_ENTITY_ID=your_entity_id -- npx -y @clearvo/mcp

Find your entity ID in Settings → Business Profile, or run list_entities after setup. Then restart Claude Code — the clearvo server will appear in /mcp.

Add to ~/.cursor/mcp.json for global use, or .cursor/mcp.json inside a project.

~/.cursor/mcp.json

{
  "mcpServers": {
    "clearvo": {
      "command": "npx",
      "args": ["-y", "@clearvo/mcp"],
      "env": {
        "CLEARVO_API_KEY": "csk_live_..."
      }
    }
  }
}

Add to Windsurf's global MCP settings file at ~/.codeium/windsurf/mcp_settings.json.

~/.codeium/windsurf/mcp_settings.json

{
  "mcpServers": {
    "clearvo": {
      "command": "npx",
      "args": ["-y", "@clearvo/mcp"],
      "env": {
        "CLEARVO_API_KEY": "csk_live_..."
      }
    }
  }
}

VS Code 1.99+ with Copilot Agent: create .vscode/mcp.json in your project. For Cline or Continue extensions, use mcpServers format instead of servers.

.vscode/mcp.json

{
  "servers": {
    "clearvo": {
      "command": "npx",
      "args": ["-y", "@clearvo/mcp"],
      "env": {
        "CLEARVO_API_KEY": "csk_live_..."
      }
    }
  }
}

3

Test it

Restart Claude Code, then paste this into a chat:

Example prompt

Use clearvo to get the e-invoicing requirements for Italy, then submit a
test invoice for €1,000 from Clearvo Test Ltd (IE1234567T) to Acme SpA
(IT12345678901, Milan) for "Software licence Q3 2026"

Claude will call get_requirements, then submit_invoice, and return a referenceId you can poll for clearance status.

Available tools

The MCP server exposes 18 tools. Claude selects the right one automatically based on what you ask.

Tool	What it does
`submit_invoice`	Submit a B2B invoice to Italy SDI, Poland KSeF, Romania ANAF, or any of 20+ supported authorities
`poll_status`	Check clearance status — PENDING, ACCEPTED, REJECTED, DUPLICATE, UNROUTABLE, DELIVERED, or UNDELIVERED
`calculate_tax`	Calculate VAT, GST, or sales tax for a transaction in 100+ countries
`validate_tax_number`	Validate a VAT number against EU VIES, HMRC, Brreg, ABN, or 100+ other authorities
`get_requirements`	Get country requirements: mandate dates, VAT number format, Peppol scheme, authority portal URL
`list_entities`	List the business entities under your account
`create_entity`	Create a new legal entity and receive an entity-scoped API key
`list_invoices`	List and filter previously submitted invoices by country or status
`list_products`	List the product catalogue — products store pre-classified tax categories to skip re-classification on every invoice
`create_product`	Create a product with a name, SKU, and tax category slug
`update_product`	Update a product — most commonly to set or correct its tax category after a `calculate_tax` call

Example: submit an invoice to Italy

Here is what happens when you ask Claude to submit an Italian invoice end-to-end.

1. Claude calls `get_requirements`

get_requirements response

{
  "country": "IT",
  "countryName": "Italy",
  "eInvoicingMandatory": true,
  "mandatoryFrom": "2019-01-01",
  "authority": "Agenzia delle Entrate (SDI)",
  "vatNumberFormat": "IT followed by 11 digits",
  "vatNumberRegex": "^IT[0-9]{11}$",
  "peppolScheme": "0211",
  "supportedDocumentTypes": [
    { "code": "380", "name": "Invoice" },
    { "code": "381", "name": "Credit note" }
  ]
}

2. Claude calls `submit_invoice`

submit_invoice response

{
  "referenceId": "IT-2026-001",
  "status": "PENDING",
  "message": "Invoice submitted to SDI. Use poll_status to track clearance."
}

3. Claude calls `poll_status` until accepted

poll_status response (after ~30s)

{
  "referenceId": "IT-2026-001",
  "status": "ACCEPTED",
  "clearanceStatus": "ACCEPTED",
  "clearanceStatusLabel": "Cleared by SDI",
  "updatedAt": "2026-06-24T14:32:01Z"
}

ℹ

Italy SDI typically clears within 5 seconds to 5 minutes. Poland KSeF is immediate. Romania ANAF can take up to 30 minutes. The MCP server returns the referenceId immediately — Claude can poll on your behalf.

TypeScript SDK

For programmatic use in Node.js or browser TypeScript projects.

          Install
          bash
        

npm install @clearvo/sdk

          Calculate tax (B2B DE → FR, reverse charge)
          typescript
        

import { ClearvoClient } from '@clearvo/sdk';

const client = new ClearvoClient({ apiKey: process.env.CLEARVO_API_KEY! });

const result = await client.calculateTax({
  currency: 'EUR',
  seller: { address: { country: 'DE' } },
  customer: {
    type: 'B2B',
    taxId: 'FR12345678901',
    billingAddress: { country: 'FR' },
  },
  lineItems: [{ id: '1', amount: 10000, productName: 'SaaS subscription' }],
});

console.log(result.taxCode);          // 'K'  — intra-EU reverse charge
console.log(result.summary.totalTax); // 0
console.log(result.lineItems[0].rate); // 0

          Create an entity and receive an API key
          typescript
        

const entity = await client.createEntity({
  legalName: 'Acme GmbH',
  country: 'DE',
  vatNumber: 'DE123456789',
});

// entity.apiKey — save this immediately, shown once only
console.log(entity.entityId);
console.log(entity.apiKey); // csk_live_...

          Validate a VAT number
          typescript
        

const result = await client.validateTaxNumber('GB', 'GB123456789');
// { valid: true, status: 'VALID', name: 'Acme Ltd', country: 'GB' }

CLI

Zero-install CLI via npx. Useful for CI pipelines and quick testing.

          Usage
          bash
        

# Set your API key once
export CLEARVO_API_KEY=csk_live_...

# List entities
npx @clearvo/cli entities list --pretty

# Get country requirements
npx @clearvo/cli requirements --country IT --pretty

# Validate a tax number
npx @clearvo/cli validate-tin --country DE --number DE123456789

# Submit an invoice from a JSON file
npx @clearvo/cli send invoice.json --pretty

# Poll invoice status
npx @clearvo/cli status ref-abc123 --pretty

# Calculate tax from a JSON file
npx @clearvo/cli calculate transaction.json --pretty

Or install globally: npm install -g @clearvo/cli

Authentication

Key prefix	Environment	Use for
`csk_live_...`	Production	Real authority submissions
`csk_test_...`	Sandbox	Development and testing — no real authority calls

Entity-scoped keys are required for submit_invoice and calculate_tax. Account-scoped keys work for list_entities and create_entity. Get both at app.clearvo.io/settings.

The API key returned from create_entity is shown once only — it is never stored in plaintext. Save it immediately to a secrets manager (AWS Secrets Manager, Azure Key Vault, etc.).

Ready to submit your first invoice?

Production API key issued in seconds. No sales call.

Get your free API key