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 31 tools. Claude selects the right one automatically based on what you ask.

Tool	What it does
Invoicing
`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
`list_invoices`	List and filter invoices by country, status, or `direction` — pass `direction: "outbound"` for invoices you submitted, `"inbound"` for invoices you received as a buyer (currently Poland KSeF only)
`get_invoice`	Fetch full detail for one invoice — event log, authority references, rejection reason, submitted XML
`poll_pl_inbox`	Fetch new invoices received from suppliers via Poland KSeF (the buyer inbox) — KSeF has no push mechanism, so call this to pull the latest received invoices
`get_requirements`	Get country requirements: mandate dates, VAT number format, Peppol scheme, authority portal URL
Tax calculation
`calculate_tax`	Calculate VAT, GST, or sales tax for a transaction in 100+ countries
`list_tax_calculations`	List committed tax calculations — jurisdiction, amounts, tax totals, customer type
`get_tax_settings`	Read account-level tax calculation settings — VAT validation mode, default tax category, US address precision
`update_tax_settings`	Update account-level tax calculation settings
`validate_tax_number`	Validate a VAT number against EU VIES, HMRC, Brreg, ABN, or 100+ other authorities
`validate_tax_numbers_batch`	Validate up to 20 tax numbers in a single request
Tax registrations
`list_registrations`	List an entity's tax registrations and obligations — VAT by country, OSS/IOSS schemes, compliance threshold status
`add_registration`	Record a new tax registration — VAT, IOSS, OSS, or any other scheme
`set_registration_collection`	Set the date a registration starts collecting tax — required before it applies to any calculation
Entities & team
`list_entities`	List the business entities under your account
`create_entity`	Create a new legal entity and receive an entity-scoped API key
`update_entity`	Update an entity's name or business profile address, or confirm it has no tax registrations yet
`invite_team_member`	Invite a teammate to your Clearvo account by email
`get_setup_status`	Check what's left to finish setting up the account — mirrors the dashboard's "Getting Started" checklist
Authority credentials
`set_pl_credentials`	Register Poland KSeF credentials (NIP + API token) — a token needs "dostęp do faktur" (access) permission to receive invoices, not just "wysyłka faktur" (send)
`set_hu_credentials`	Register Hungary NAV Online Számla technical user credentials
`set_ar_credentials`	Register Argentina AFIP WSFE certificate credentials
Product catalogue
`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
Webhooks
`list_webhooks`	List registered webhook endpoints
`create_webhook`	Register a new webhook to receive real-time invoice status events
`delete_webhook`	Deactivate a webhook endpoint
Exemption certificates
`create_exemption_certificate`	Record a buyer's tax exemption certificate so it auto-applies during `calculate_tax`
`upload_exemption_document`	Attach the signed certificate PDF to an exemption certificate

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

Most tools — submit_invoice, calculate_tax, tax registrations, and more — accept either key type: entity-scoped keys resolve automatically, account-scoped keys need an entityId specified per call. create_entity is the one exception — it requires an account-scoped key, since it creates a new entity under the account. Get a key 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