Build with an agent
Everything here is written to be read by an AI assistant as well as a person, so you can hand the integration to one.
Where agents read
| What | Where |
|---|---|
| An index of the site and docs | /llms.txt |
| The product, plans and API in one file | /llms-full.txt |
| Any page as Markdown | Add .md to its address, such as /docs/quickstart.md, or send Accept: text/markdown. |
| Every endpoint, request and response | openapi.json |
| Every rate and threshold, no key | /v1/rates |
The MCP server
Every endpoint is also a tool on the MCP server at https://api.checktakehomepay.co.uk/mcp, such as calculate_take_home, gross_from_net, employer_cost and decode_tax_code, so an assistant can work out UK pay instead of guessing it. With a key, calculations count on its plan; without one, reference data is free and calculations come from a small shared daily allowance.
claude mcp add --transport http check-take-home-pay https://api.checktakehomepay.co.uk/mcp \
--header "Authorization: Bearer $CHECKTAKEHOMEPAY_API_KEY"{
"mcpServers": {
"check-take-home-pay": {
"type": "http",
"url": "https://api.checktakehomepay.co.uk/mcp",
"headers": { "Authorization": "Bearer <your key>" }
}
}
}A key an agent gets for itself
An agent can sign itself up, with no email: it gets a key on the free plan (100 calculations a month) and a claim_url for its person. Opening that link while signed in moves the key, its calls and its usage into their account, where they can choose a plan with more.
curl https://api.checktakehomepay.co.uk/api/agent/signup \
-H "Content-Type: application/json" \
-d '{"name": "Payslip helper for Acme", "use_case": "Checking payslips against HMRC rules"}'The key is in api_key, shown once. One address can sign up 20 agents a day.
A prompt to start from
Paste this into your assistant, with what you’re building at the end:
Use the Check Take Home Pay API for UK pay calculations. Read https://checktakehomepay.co.uk/llms.txt and the OpenAPI document at https://api.checktakehomepay.co.uk/openapi.json first.
- Send the key from the CHECKTAKEHOMEPAY_API_KEY environment variable as "Authorization: Bearer <key>", from server code only.
- Money is pounds and pence; recurring pay is { "amount", "per" }.
- Don't send fields the OpenAPI document doesn't list: unknown fields are rejected.
- On an error, branch on error.code, show error.message to the developer, and retry only RATE_LIMITED (after Retry-After seconds), UNAVAILABLE and INTERNAL. QUOTA_EXCEEDED means the free plan's month is used: show its upgrade_url.
- Read X-Quota-Remaining to see how many of the month's calculations are left.
- Show the response's assumptions where a person sees the figures.
What I'm building: Trying it without a key
An agent can check its understanding against the reference data before it has a key: GET /v1/rates returns every rate and threshold, and GET /v1/tax-codes/{code} decodes a tax code.
GET /v1/rates No keycURL
curl https://api.checktakehomepay.co.uk/v1/ratesNode.js
const response = await fetch('https://api.checktakehomepay.co.uk/v1/rates');
const result = await response.json();Python
import requests
response = requests.get("https://api.checktakehomepay.co.uk/v1/rates")
result = response.json()