VATBuild Developer API & MCP Documentation

VATBuild exposes a REST API and an MCP (Model Context Protocol) server so that AI agents, automation scripts, and accountancy software integrators can drive the UK construction VAT routing engine without a browser session.

What you can do

• Classify a line item — POST a single invoice line description to POST /api/v1/check-line-item and receive the VAT treatment, reclaimable amount, and the HMRC Notice 708 rule that fired. No authentication required. No data is stored.
• Create and manage projects — Create org-scoped construction projects and receive synchronous VAT treatment estimates.
• Submit invoices for AI extraction — Upload invoice references for automated AI extraction and classification.
• Connect via MCP — Use the Model Context Protocol endpoint at POST /mcp to integrate VATBuild tools directly into Claude, ChatGPT, Copilot, or any MCP-compatible agent.

Who this is for

• AI agent builders — wire VATBuild VAT routing into Claude, ChatGPT, or any MCP-compatible assistant.
• Accountancy software integrators — batch-classify line items or fetch project summaries via REST.
• Automation scripts — shell, Python, or Node.js scripts that process construction invoices.

Quick-start

Path	Description
REST — POST /api/v1/check-line-item	Classify a line item with no auth
MCP — Claude Desktop config	Add VATBuild to your Claude MCP client
curl examples	Shell one-liners for every major endpoint

REST quick-start

curl -s -X POST https://vatbuild.com/api/v1/check-line-item \
  -H "Content-Type: application/json" \
  -d '{
    "context": {
      "claimantRoute": "self_build_431nb",
      "newDwelling": "yes"
    },
    "item": {
      "lineText": "Structural brickwork and blockwork",
      "netAmount": "5000.00",
      "vatCharged": "0.00",
      "supplyType": "labour"
    }
  }'

Response:

{
  "ok": true,
  "data": {
    "outcome": { "claimRoute": "zero_at_source", ... },
    "reclaimAmount": "0.00",
    "firedRuleId": "rule_4a7f3c8e2b916d05",
    "rule": {
      "label": "431NB qualifying service — zero-rated",
      "noticeRef": "Notice 708 s3.1",
      "explanation": "Contractor services on a qualifying 431NB new build are zero-rated at source — no VAT to reclaim."
    }
  }
}

MCP quick-start

See mcp/README.md for Claude Desktop configuration.

Integration paths

Integration	Auth	Best for
POST /api/v1/check-line-item	None	Stateless classification, batch pipelines
POST /mcp	Bearer API key	AI agents (Claude, ChatGPT, Copilot)
POST /api/v1/projects + /invoices	Bearer API key	Full project automation

Files in this repository

File	Description
README.md	This file — overview and quick-start
routing-guide.md	VAT claimant routes, outcomes, and claim actions
openapi.yaml	Full OpenAPI 3.1 spec for the REST API
mcp-tool-reference.md	Full MCP tool reference — input/output schemas, error codes, claimRoute values
Settings → API Keys → System Prompts	Personalised system prompts for Claude, ChatGPT, Gemini, and Copilot (auth-gated, watermarked per account)
examples/curl/examples.sh	curl one-liners for every endpoint
examples/python/README.md	Python examples guide
examples/python/basic_query.py	Single line-item classification
examples/python/invoice_check.py	Batch classification with summary table
examples/javascript/README.md	JavaScript examples guide
examples/javascript/basic_query.js	Single line-item classification (Node.js)
claude-integration.md	Full Claude Desktop / Cursor / Zed integration guide — config, agent workflow, OAuth/PKCE
chatgpt-integration.md	Full ChatGPT desktop / in-browser / Custom GPT Actions integration guide
gemini-integration.md	Full Gemini CLI / AI Studio / Vertex AI Agent Builder integration guide
copilot-integration.md	Full GitHub Copilot Chat / Copilot Studio / M365 extensibility integration guide
mcp/claude-config.json	Claude Desktop MCP configuration
mcp/README.md	MCP setup guide
CHANGELOG.md	API changelog (Keep a Changelog format)

Authentication

Public endpoints (POST /api/v1/check-line-item, GET /api/v1/reference/routes) require no authentication.

Authenticated endpoints require a Bearer API key:

Authorization: Bearer vb_live_<64 hex characters>

API keys are created and managed in the VATBuild dashboard under Settings → API Keys.

Rate limits

Endpoint	Limit
POST /api/v1/check-line-item	60 req/min per IP
GET /api/v1/reference/*	20 req/min per IP
POST /api/v1/projects, POST /api/v1/invoices	10 req/min per key
POST /mcp (all MCP tools)	60 req/min per key
route_line_item, answer_vat_complex_question (MCP)	10 req/min per key

All 429 responses include a Retry-After header.

Support

• API reference: openapi.yaml
• MCP tool reference: mcp-tool-reference.md
• Contact: https://vatbuild.com