MCP Server for EU VAT Validation

The official Model Context Protocol server for vatnode. Plug Claude Desktop, Claude Code, Cursor, ChatGPT, Cline, Continue — or anything that speaks MCP — into vatnode and let the agent validate EU VAT numbers against the live VIES register and look up VAT rates inside the conversation.

Why an AI Workflow Needs Real VAT Data

Language models are confident and frequently wrong about tax. Ask one for the VAT rate in Finland and it may quote 24% — the rate before the September 2024 increase to 25.5%. Ask it whether a VAT number is valid and it has no way to know: validity is a fact held only by the EU VIES register, updated continuously by 27 national tax authorities. A model cannot validate a VAT number any more than it can check whether your flight is on time. It can only guess.

For any agent that touches invoicing, onboarding, B2B sign-up or compliance, a wrong answer is not a harmless slip — it is a mis-issued invoice or a reverse-charge claim you cannot defend. The MCP server replaces the guess with a tool call: bundled rate and format data refreshed daily from the EU Commission TEDB, and live VIES validation through the vatnode API for the EU-27 plus Northern Ireland (XI).

Tools

Five focused tools, each with a description tuned for accurate selection by the agent. The four free tools work fully offline — VAT rates and format patterns are bundled in the package and refreshed daily from the EU Commission TEDB. Only live VIES validation calls the vatnode API.

Install

For Claude Desktop, open claude_desktop_config.json (on macOS in ~/Library/Application Support/Claude/) and add an mcpServers.vatnode entry. In Cursor, paste the same block under Settings → MCP → Add new server.

{
  "mcpServers": {
    "vatnode": {
      "command": "npx",
      "args": ["-y", "vatnode-mcp"],
      "env": {
        "VATNODE_API_KEY": "vat_live_..."
      }
    }
  }
}

Restart the client — the vatnode tools appear in the tool picker. Any other MCP-compatible client works the same way: point it at npx -y vatnode-mcp with VATNODE_API_KEY in the environment.

SKILL.md — the No-MCP Path

Plenty of agents never speak MCP: a coding assistant writing an integration, a shell-based agent, a custom LLM pipeline. For those, vatnode publishes a single self-contained brief at vatnode.dev/SKILL.md. Fetch it and the agent knows the whole API without crawling the docs site.

It is an Agent Skill-formatted Markdown file — frontmatter plus prose — so you can drop it straight into a skills directory, paste it into a system prompt, or let a coding agent read it before writing the integration. It covers:

• Which endpoints need no account at all (rates, format checks) and which need a key
• Authentication — Bearer header, never the URL
• The full response envelope: valid, checkId, verifiedAt, consultationNumber, source, countryVat
• The consultation-number contract and the one-time requester VAT setup in dashboard Settings
• Error codes worth handling — INVALID_REQUESTER, VIES_UNAVAILABLE — and why a 503 is not an invalid number
• Scope: EU-27 + XI for validation, wider coverage for rates

There is also /llms.txt — the long-form machine spec with every field and endpoint — and /agents.txt for a terse orientation file. MCP, SKILL.md and llms.txt all describe the same API; pick whichever your runtime can consume.

What It Looks Like in Chat

Once connected, you talk to the agent normally — it picks the right tool from the description.

You: What's the VAT rate in Finland and Germany?

Claude: (calls get_country_vat_rates for FI and DE — free, no key)
Finland's standard VAT is 25.5%, Germany's is 19%. Finland has reduced
rates of 13.5% and 10%; Germany has 7%.

You: Is IE6388047V a valid VAT?

Claude: (calls validate_vat_number — requires API key)
Yes, it's valid. Registered to GOOGLE IRELAND LIMITED at Gordon House,
Barrow Street, Dublin 4.

Configuration

Coverage

• Live VIES validation for all EU-27 member states plus Northern Ireland (XI)
• VAT rate and format data for 45 European countries, refreshed daily from the EU Commission TEDB
• VIES consultation number on qualified live validations, when a requester VAT is supplied — for audit evidence
• Registered company name and address returned where the member state publishes it
• Four offline tools that need no API key and never make a network call

Privacy & Security

• The server runs locally on your machine via npx — no third-party proxy
• Your API key stays in your MCP client config and is never sent anywhere except directly to api.vatnode.dev
• VAT numbers passed to validate_vat_number are logged on the vatnode side, same as any direct API call — see the privacy policy
• The four free tools never make a network call — rate and format data is bundled in the package

Why Use the Official Server

Third-party MCP marketplaces sometimes ship VAT or tax-validation wrappers built around the vatnode API. Using vatnode-mcp directly is the only way to:

• Keep your API key on your own machine, not in a hosted middle-tier
• Get tool descriptions that track the real API surface release-by-release
• Skip a subscription tier on top of your vatnode plan
• Read the source — it's open and every release is signed with npm provenance

FAQ