VATBuild MCP Server

VATBuild is a UK construction VAT reclaim platform built on HMRC Notice 708. This MCP server lets any AI assistant classify invoice line items, manage VAT projects, and route reclaim decisions — all without leaving the chat interface.

Endpoint: POST https://vatbuild.com/mcp (JSON-RPC 2.0, Streamable HTTP)

Protocol: Model Context Protocol (MCP), stateless transport

Getting started

You need a free VATBuild account and an API key before calling the authenticated tools.

Option A — Create an account in your browser

Visit vatbuild.com and sign up. Then go to Settings → API Keys, create a key, and copy the value — it is shown only once. Keys have the format vb_live_<64 hex characters>.

Option B — Bootstrap an account via MCP itself

The create_account and authenticate_account tools are public (no key required). An AI agent can call create_account to register a new account and immediately receive an API key without any browser interaction:


Ask your AI: "Create a VATBuild account for me using the create_account tool."

The returned apiKey can then be used for all subsequent authenticated tool calls in the same session.

All tools

|---|---|---|

Tool	Auth	Description
`check_line_item`	Public	Classify a single invoice line against HMRC Notice 708 — stateless, no persistence
`create_account`	Public	Create a free VATBuild account and receive an API key immediately
`authenticate_account`	Public	Retrieve a fresh API key for an existing account
`check_account_status`	Bearer key	Return account status — verification, plan, and pending actions
`set_up_project`	Bearer key	Create a new VAT project with a scheme and building details
`list_projects`	Bearer key	List all projects in the authenticated user's organisation
`assess_project_eligibility`	Bearer key	Run an HMRC Notice 708 eligibility check before uploading invoices
`list_invoices`	Bearer key	List invoice documents and their extraction status for a project
`list_line_items`	Bearer key	Retrieve paginated invoice line items for a project
`route_line_item`	Bearer key	Classify and persist a VAT routing decision to a project
`answer_vat_complex_question`	Bearer key	Submit an answer to a pending complex-VAT question (ESM, supply-and-install, etc.)
`reclassify_companion_items`	Bearer key	Re-route sibling items on an invoice after a complex-VAT answer
`submit_invoice_data`	Bearer key	Upload invoice image or document data for AI extraction and classification

For full input/output schemas for every tool, see mcp-tool-reference.md.

API key scopes

A VATBuild API key grants access to tools within its granted scopes:

projects:read — read project data, line items, invoices, and eligibility
projects:write — create and update projects
line_items:write — route line items, answer VAT questions, re-classify companion items, and submit invoice data
jobs:read — poll extraction job status via the REST API (GET /api/v1/jobs/{jobId})
invoices:write — submit invoice data (submit_invoice_data) and lock/manage invoices via the REST API. Use this for upload-only keys that should not grant manual line-item override access.

check_line_item, create_account, and authenticate_account are publicly accessible without any key. check_account_status requires a Bearer key but returns a structured unauthenticated error (not HTTP 401) when called without one. All other tools return a structured registration_required payload (HTTP 200, not 401) when called without a valid key, so AI agents can present a signup prompt rather than an error.

Step 1 — Configure Claude Desktop

Open (or create) your Claude Desktop MCP configuration file:

|---|---|

OS	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Add the VATBuild server to the mcpServers object:


{
  "mcpServers": {
    "vatbuild": {
      "url": "https://vatbuild.com/mcp",
      "headers": {
        "Authorization": "Bearer vb_live_<your-64-hex-key>"
      }
    }
  }
}

If you already have other MCP servers configured, merge the "vatbuild" entry into the existing mcpServers object — do not replace the whole file.

A ready-to-paste template is in claude-config.json. Replace <YOUR_VATBUILD_API_KEY> with your actual key.

Step 2 — Restart Claude Desktop

Quit and relaunch Claude Desktop. The VATBuild tools should appear in the tool list (look for the hammer icon or "Add from MCP" in the composer).

Step 3 — Add the system prompt

For best results, add the VATBuild system prompt to your Claude project or conversation instructions. Download your personalised copy from Settings → API Keys → System Prompts inside your VATBuild account.

Step 4 — Test the connection

Ask Claude:

> "Use the VATBuild check_line_item tool to classify this line: structural brickwork, £5,000 net, £0 VAT, labour supply type, on a self_build_431nb new build."

Claude should call check_line_item and return the classification with the HMRC rule explanation.

Other MCP clients

The endpoint is POST https://vatbuild.com/mcp (JSON-RPC 2.0, Streamable HTTP transport). It also responds at POST https://vatbuild.com/sse — both paths are identical.

Generic JSON config (any MCP-compatible client):


{
  "endpoint": "https://vatbuild.com/mcp",
  "transport": "streamable-http",
  "auth": {
    "type": "bearer",
    "token": "vb_live_<your-64-hex-key>"
  }
}

CLI / curl — quick test without a client:


curl -X POST https://vatbuild.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "check_line_item",
      "arguments": {
        "context": {
          "projectType": "new_build",
          "newDwelling": "yes",
          "buildingType": "detached house",
          "claimantRoute": "self_build_431nb"
        },
        "item": {
          "lineText": "Structural brickwork",
          "netAmount": "5000",
          "vatCharged": "0",
          "supplyType": "labour"
        }
      }
    }
  }'

check_line_item is public — no Authorization header needed for this test. Add -H "Authorization: Bearer vb_live_..." for authenticated tools.

Origin policy: The /mcp endpoint is intended for server-to-server requests and CLI agents. Requests without an Origin header (all server and CLI clients) are allowed. Browser-origin requests from a domain not listed in the server's APP_ORIGIN config are rejected with 403 Forbidden — use the REST API (POST /api/v1/check-line-item) from browser clients instead.

Rate limits