Register your application on the HMRC Developer Hub at developer.service.hmrc.gov.uk and subscribe to the VAT (MTD) API v1.0; obtain OAuth 2.0 client credentials for the production environment.
Complete the OAuth 2.0 authorization code flow on behalf of the business (or agent); the business must authorize your application through HMRC's grant page, after which you receive an access token scoped to write:vat.
Call GET /organisations/vat/{vrn}/obligations with date range parameters to retrieve open obligation periods and identify the periodKey for the period you intend to file.
Calculate the 9-box VAT figures from the business's accounting records and POST them to /organisations/vat/{vrn}/returns with the periodKey and set the finalised boolean to true; HMRC will reject submissions where finalised is false.
Handle the response: a 201 Created confirms acceptance; a 400 with error code INVALID_REQUEST indicates a calculation mismatch — HMRC validates that box 5 equals box 3 minus box 4.
Retrieve a copy of the submitted return via GET /organisations/vat/{vrn}/returns/{periodKey} and store it with the submission timestamp as evidence of timely filing.
Known gotchas
The finalised field must be set to true or HMRC will not accept the return — omitting it or setting it to false is a common integration mistake that results in a silent rejection.
HMRC validates internal consistency of the 9 boxes at submission time; a mismatch between box 5 and the difference of boxes 3 and 4 returns a 400 error — pre-validate arithmetic before calling the endpoint.
Access tokens expire; implement token refresh logic using the refresh token before making the return submission call, as a mid-flow expiry will require the user to re-authorize.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp