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.
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.POST /mcp to integrate VATBuild tools directly into Claude, ChatGPT, Copilot, or any MCP-compatible agent.| 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 |
curl -s -X POST https://api.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."
}
}
}
See mcp/README.md for Claude Desktop configuration.
| 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 |
| 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 |
| mcp/claude-config.json | Claude Desktop MCP configuration |
| mcp/README.md | MCP setup guide |
| CHANGELOG.md | API changelog (Keep a Changelog format) |
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.
| 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.