Not tax advice. Computation tools only. Have a professional check your work before filing.
openaccountants
All posts

We Built an MCP Server So AI Agents Stop Hallucinating Tax Rules

Michael Cutajar|20 May 2025|4 min read
mcpaideveloperstaxopen-source

Every AI model hallucinates. That's a known problem. But when the hallucination is a tax rate, a filing deadline, or a deduction that doesn't exist — someone ends up with a penalty from their tax authority.

I'm an accountant who codes. Over the past year I've been watching developers build AI agents that handle financial tasks — categorising transactions, computing tax, preparing returns. The agents are impressive. The tax logic is not.

Here's a real example: I asked Claude to compute self-employment social security contributions for a Maltese freelancer earning €35,000. It applied the wrong rate band, used an outdated cap, and missed the minimum contribution floor entirely. The output looked perfect. A developer would ship it. A client would trust it. The tax authority would reject it.

The core issue isn't that AI is bad at tax. It's that AI has no authoritative source to reference. It's working from whatever fragments about tax law appeared in its training data — forum posts, outdated blog articles, scraped government pages that may have changed since.

What We Built

OpenAccountants is an open-source library of tax computation skills — structured markdown files that contain the actual rules for each country's tax system. Rates, thresholds, exemptions, filing deadlines, computation steps, all cited to primary legislation.

We exposed these skills through an MCP server. If you're not familiar with MCP (Model Context Protocol), it's a standard created by Anthropic that lets AI agents discover and use external tools and knowledge sources. Think of it as an API that AI agents natively understand.

Our MCP server gives any agent access to three tools:

  • list_skills — browse all published skills, filter by country or tax type
  • get_skill — fetch the full verified markdown for a specific skill
  • get_skill_sections — get parsed sections for step-by-step rule application

And one prompt:

  • skill-review — loads a skill and applies every rule to a taxpayer's scenario, flagging items that need human accountant review

When an agent connects to our MCP server and a user asks "help me with my German VAT return," the agent calls list_skills with jurisdiction "DE," pulls the German UStVA skill, and follows the verified rules instead of improvising.

The Architecture

The skills themselves are plain markdown files in a GitHub repo. No proprietary format, no vendor lock-in. Any LLM can read them — upload them to a Claude Project, feed them to ChatGPT, or connect via MCP for automatic discovery.

The MCP server is a lightweight endpoint that reads from a Supabase database where skills are indexed with metadata (jurisdiction, tax type, quality tier, verifier credentials). It runs as an API route inside our Next.js app, so there's no separate infrastructure to maintain.

Agent → MCP Protocol → openaccountants.com/api/mcp → Supabase → Skill markdown

The server is listed on the official MCP Registry, Smithery, Glama, and several other directories. Any MCP-compatible agent can discover and connect to it automatically.

The Three-Tier Rule

Every skill follows a three-tier classification system:

  • T1 (Deterministic): Clear-cut rules. "The standard VAT rate is 18%." No judgment needed. The AI applies these directly.
  • T2 (Reviewer judgment required): The rule exists but applying it requires professional judgment. "Is this supply exempt under Schedule 5 Item 1?" The AI flags these for an accountant to review.
  • T3 (Escalate): Complex, ambiguous, or high-risk. "Does the taxpayer qualify for the participation exemption?" The AI stops and tells the user to consult a professional.

No LLM ever touches the numbers in T1 computations. The skill provides the formula, the rates, and the thresholds. The AI's job is to plug in the taxpayer's data and follow the formula — not to decide what the formula should be.

The Verification Problem

Here's our honest gap: we have 371 skills across 134 countries, but most are Q3 — AI-drafted with citations but not verified by a practitioner in that jurisdiction. They're better than raw AI output, but they're not trustworthy enough to use without review.

We need qualified accountants in each country to review the skills and sign off. The verifier's name and credentials go on the skill permanently. One South African accountant found us through Claude, reviewed the South Africa skills, and is now the named verifier for that jurisdiction.

If you're a developer building AI agents that touch finance, the skills are at github.com/openaccountants/openaccountants. If you're an accountant, go to openaccountants.com and claim your country.

The MCP endpoint is live at openaccountants.com/api/mcp. Connect it and your agent stops guessing about tax.