New France e-invoicing mandate goes live September 2026 — our implementation is ready. See all mandates →
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 tax 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 its status.

Working across several business profiles

When you connect an AI tool by signing in (instead of an API key), you choose what the connection may act on. If you belong to two or more business profiles, the consent screen offers All my business profiles as well as a single one.

  • Access follows your account live. A business profile you are added to later appears without reconnecting, and access you lose is removed straight away.
  • Your role in each business profile still applies. Where you are a viewer or auditor, the connection stays read-only for that profile.
  • Account administrators choose one business profile per connection.
  • A connection made for one business profile behaves exactly as before: you never need to pass entityId.

Every tool except reference-data and account-level ones (for example list_tax_categories, validate_tax_number, create_entity) takes an optional entityId. list_entities returns only the business profiles the connection may act on. If a connection covers several business profiles and a call has no entityId, the tool does not guess: it replies asking you to choose one and call list_entities. A business profile outside the connection's access is refused.

Example prompt
List my business profiles with clearvo, then calculate tax for a 500 EUR
sale to a German consumer in the Irish business profile.

Claude calls list_entities, picks the matching business profile, and passes its id as entityId to calculate_tax.

Available tools

The MCP server exposes more than 100 tools — every public API operation is available — and Claude selects the right one automatically based on what you ask. The table below lists the most commonly used ones; ask Claude "what Clearvo tools can you use?" for the full list.

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 invoice status — RECEIVED, PENDING, WAITING_FOR_YOU, WAITING_FOR_PLATFORM, ACCUMULATED, COMPLETED, REJECTED, CANCELLED, SKIPPED, or NOT_APPLICABLE, with stage, reason, issues and customerResponse
list_invoices List and filter invoices by country, status, reason, buyer response or document family, with cursor pagination. Received (inbound) invoices carry their intake channel, validation summary and attachments
get_invoice Fetch full detail for one invoice — event log, authority references, rejection reason, submitted XML
list_invoice_attachments List the supporting files sent with, or received on, an invoice, with a download URL for each stored file. Read-only; the files themselves download through the SDK, CLI or API
get_requirements Get country requirements: mandate dates, VAT number format, Peppol scheme, authority portal URL
list_country_coverage List the countries and mandates covered, with status (live, beta, coming soon, not supported, no mandate) and go-live date where confirmed
Tax calculation
calculate_tax Calculate tax (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. Optional companyName adds a name match against the registered name
validate_tax_numbers_batch Validate up to 20 tax numbers in a single request
query_tax_number_check_history Find the stored authority check that applied to tax numbers on a given date, with its proof reference
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 profiles this connection can act on (all of them for an account-scoped key or an "All my business profiles" connection). Use the returned id as entityId on other tools
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 customer'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": "COMPLETED",
  "stage": "cleared",
  "reason": "ACCEPTED",
  "statusLabel": "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',
  supplier: { billingAddress: { country: 'DE' } },
  customer: {
    taxId: 'FR12345678901',   // a verified tax ID is what makes this B2B
    // b2bOverride: true,      // use instead when you know the buyer is a business but have no tax ID
    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

# List country coverage (no API key needed)
npx @clearvo/cli coverage --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 --country IT --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 and connections covering several business profiles need an entityId specified per call (see working across several business profiles). 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