# 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](https://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](../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:

```json
{
  "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](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):**

```json
{
  "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:**

```bash
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

| Endpoint | Limit |
|---|---|
| `POST /mcp` — all tools, unauthenticated (by IP) | 60 requests/min |
| `POST /mcp` — all tools, authenticated (by API key) | 60 requests/min |
| `route_line_item`, `answer_vat_complex_question`, `reclassify_companion_items` | 10 requests/min per API key |
| `create_account`, `authenticate_account` | 3 requests/hour per IP |

All 429 responses include a `Retry-After` header.

---

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| Tools don't appear in Claude | Config file not found or JSON is invalid | Validate the JSON at jsonlint.com and check the file path |
| `401 Unauthorized` | API key missing or invalid | Check the `Authorization: Bearer ...` header value |
| `403 Forbidden` | Browser-origin request blocked | Use a non-browser client; MCP is server-to-server only |
| `429 Too Many Requests` | Rate limit exceeded | Wait for `Retry-After` seconds before retrying |
| `503 Service Unavailable` | Server still initialising on cold start | Retry in 5 seconds |
| Authenticated tool returns `registration_required` | Bearer key missing or revoked | Check your API key in Settings → API Keys on vatbuild.com |

---

## See also

- [Full tool reference](../mcp-tool-reference.md) — per-tool input/output schemas, error codes, and field descriptions
- System prompts — download personalised copies from **Settings → API Keys → System Prompts** inside your VATBuild account
- [ChatGPT connection guide](../../chatgpt-mcp-connection-guide.md) — OAuth-based setup for ChatGPT Custom Connectors
- [OpenAPI spec](../openapi.yaml) — REST API OpenAPI 3.1 spec (`POST /api/v1/check-line-item` companion endpoint)