reference-data
N American govt data, cited to source: rates, VAT, tax, wages, holidays, FX. 10 countries; USA free.
Should I use this
Quality & Safety
Based on automated analysis of tool definitions and protocol compliance.
Context Cost
This is the approximate number of tokens consumed each time the server's tools are loaded into a model's context. Higher counts reduce the attention available for other tasks.
Install
One-Click Install
Add this to your `claude_desktop_config.json` file:
{
"mcpServers": {
"reference-data": {
"url": "https://usaref.dev/mcp"
}
}
}Remote endpoints
https://usaref.dev/mcpstreamable-httpWhat it can do
Tool inventory
Tools (16)
🟢list_series
FREE. Catalog of all usaref reference-data series: supported countries, series ids, descriptions, freshness metadata and per-series URLs. Call this first to discover what data exists. Paid answer tools accept receipt=true (included in the answer price, no extra USDC) and, on a paid success, return an Ed25519 answer receipt (kind answer_receipt). That receipt is not a series certified extract and is not legal advice. Series certified extracts are GET /v1/certified/{country}/{series} at $0.25 and are not an MCP tool. Verify a receipt with verify_answer_receipt (free, public key only) against /certified/public-key. get_changes is free. get_calendar is free. register_alert registration is free.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_public_holidays(country, subdivision)
FREE. Official public-holiday calendar for a supported country, including gazetted movable holidays, with the official government source cited. Some countries also carry sub-national calendars (e.g. the German Laender): the `subdivisions` field lists them, and passing `subdivision` (ISO 3166-2, e.g. 'DE-BY') returns the national calendar merged with that region's statutory days.
Input Schema
{
"type": "object",
"properties": {
"country": {
"type": "string",
"enum": [
"bs",
"ca",
"cr",
"do",
"gt",
"hn",
"mx",
"pa",
"sv",
"us"
],
"description": "ISO country code"
},
"subdivision": {
"description": "Optional ISO 3166-2 region code (e.g. 'DE-BY'). Returns national + that region's statutory holidays, each tagged national/regional. Omit for the national calendar.",
"type": "string"
}
},
"required": [
"country"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_series(country, series, api_key)
PAID ($0.005). Current value of a reference series — e.g. series=policy-rate, vat, minimum-wage. Every value carries its official source citation, effective date, last-confirmed date and staleness flag. Pass api_key if you have one; otherwise the response explains how to pay via x402. After a 200, bind get_changes (free poll) or register_alert (HMAC push; Register: $0 · Delivery after trial: $0.10) on this series so a later gazette does not silently retire the value.
Input Schema
{
"type": "object",
"properties": {
"country": {
"type": "string",
"enum": [
"bs",
"ca",
"cr",
"do",
"gt",
"hn",
"mx",
"pa",
"sv",
"us"
],
"description": "ISO country code"
},
"series": {
"type": "string",
"description": "Series id, e.g. policy-rate, vat, minimum-wage"
},
"api_key": {
"description": "API key (bypasses x402; metered for invoicing)",
"type": "string"
}
},
"required": [
"country",
"series"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_series_history(country, series, from, to, api_key)
PAID ($0.005). Historical values of a reference series with effective date ranges, optionally filtered by from/to (YYYY-MM-DD). Pass api_key if you have one; otherwise the response explains how to pay via x402. After a 200, bind get_changes (free poll) or register_alert (HMAC push; Register: $0 · Delivery after trial: $0.10) on this series so a later gazette does not silently retire the value.
Input Schema
{
"type": "object",
"properties": {
"country": {
"type": "string",
"enum": [
"bs",
"ca",
"cr",
"do",
"gt",
"hn",
"mx",
"pa",
"sv",
"us"
],
"description": "ISO country code"
},
"series": {
"type": "string",
"description": "Series id"
},
"from": {
"description": "Earliest effective date, YYYY-MM-DD",
"type": "string"
},
"to": {
"description": "Latest effective date, YYYY-MM-DD",
"type": "string"
},
"api_key": {
"description": "API key",
"type": "string"
}
},
"required": [
"country",
"series"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢check_minimum_wage(country, amount, period, receipt, api_key)
PAID ($0.05). Compliance verdict: is a salary at, above or below the country's statutory minimum wage? Returns verdict, margin, the statutory floor and the legal instrument it rests on. Honest statuses when no enforceable floor exists or the period doesn't match the floor's period (cross-period conversion is never guessed). Pass api_key if you have one; otherwise the response explains how to pay via x402. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.25 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.
Input Schema
{
"type": "object",
"properties": {
"country": {
"type": "string",
"enum": [
"bs",
"ca",
"cr",
"do",
"gt",
"hn",
"mx",
"pa",
"sv",
"us"
],
"description": "ISO country code"
},
"amount": {
"type": "number",
"description": "Wage to check, in the country's own currency"
},
"period": {
"type": "string",
"enum": [
"month",
"day",
"hour",
"week"
],
"description": "Period the amount covers — must match the statutory floor's period"
},
"receipt": {
"default": false,
"description": "Default false. When true, a paid success includes an Ed25519 answer receipt (kind answer_receipt) at no extra USDC. Unpaid 402 and free refusals do not include one. Not a series certified extract (GET /v1/certified/{country}/{series} at $0.25; that SKU is not an MCP tool).",
"type": "boolean"
},
"api_key": {
"description": "API key (bypasses x402; metered for invoicing)",
"type": "string"
}
},
"required": [
"country",
"amount",
"period"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢compute_vat(country, amount, mode, receipt, api_key)
PAID ($0.02). VAT breakdown for an amount: net, tax and gross using the country's current statutory rate, including per-levy components where the rate is composite (e.g. Ghana VAT + NHIL + GETFund). mode=add treats the amount as net; mode=extract backs VAT out of a gross amount. Pass api_key if you have one; otherwise the response explains how to pay via x402. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.25 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.
Input Schema
{
"type": "object",
"properties": {
"country": {
"type": "string",
"enum": [
"bs",
"ca",
"cr",
"do",
"gt",
"hn",
"mx",
"pa",
"sv",
"us"
],
"description": "ISO country code"
},
"amount": {
"type": "number",
"description": "Amount in the country's own currency"
},
"mode": {
"description": "add = amount is net (default); extract = amount is gross",
"type": "string",
"enum": [
"add",
"extract"
]
},
"receipt": {
"default": false,
"description": "Default false. When true, a paid success includes an Ed25519 answer receipt (kind answer_receipt) at no extra USDC. Unpaid 402 and free refusals do not include one. Not a series certified extract (GET /v1/certified/{country}/{series} at $0.25; that SKU is not an MCP tool).",
"type": "boolean"
},
"api_key": {
"description": "API key",
"type": "string"
}
},
"required": [
"country",
"amount"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢count_working_days(country, from, to, subdivision, receipt, ...)
PAID ($0.02). Working days in a date range for a country: weekends (Egypt's Fri–Sat handled) and statutory public holidays applied, with the holidays hit by name and the next working day after the range. Range max 366 days. Pass api_key if you have one; otherwise the response explains how to pay via x402. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.25 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.
Input Schema
{
"type": "object",
"properties": {
"country": {
"type": "string",
"enum": [
"bs",
"ca",
"cr",
"do",
"gt",
"hn",
"mx",
"pa",
"sv",
"us"
],
"description": "ISO country code"
},
"from": {
"type": "string",
"description": "Range start, YYYY-MM-DD, inclusive"
},
"to": {
"type": "string",
"description": "Range end, YYYY-MM-DD, inclusive"
},
"subdivision": {
"description": "Optional ISO 3166-2 region code (e.g. 'DE-BY') to apply that region's statutory holidays on top of the national calendar. Regions are listed under `subdivisions` by get_public_holidays. Unknown code is refused free with the list.",
"type": "string"
},
"receipt": {
"default": false,
"description": "Default false. When true, a paid success includes an Ed25519 answer receipt (kind answer_receipt) at no extra USDC. Unpaid 402 and free refusals do not include one. Not a series certified extract (GET /v1/certified/{country}/{series} at $0.25; that SKU is not an MCP tool).",
"type": "boolean"
},
"api_key": {
"description": "API key",
"type": "string"
}
},
"required": [
"country",
"from",
"to"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢settlement_date(trade_date, calendars, business_days, market, instrument_class, ...)
PAID ($0.05). Settlement/value date: the date n business days after a trade date, computed on the INTERSECTION of the calendars you name, with a per-day trail showing every skipped day and why, on which calendar. Supply business_days for a cycle you are trading under, or market + instrument_class to have a settlement cycle applied that we cite to its primary source (e.g. US equities T+1 under 17 CFR 240.15c6-1(a); UK gilts T+1 by DMO convention, which is NOT the T+2 equity cycle; Japan equities T+2 but JGBs T+1). Calendars are NATIONAL statutory holiday calendars with researched statutory weekend rules (Israel Saturday-only, Gulf Friday+Saturday, India Sundays plus the 2nd and 4th Saturday), NOT CSD or exchange calendars — each response states the basis and any known divergence. Use 'eu.t2' for the euro cash leg. We refuse FREE rather than guess: beyond published calendar coverage, no cited cycle for the instrument (government bonds never inherit an equity cycle), a cycle not in force on the trade date, or FX spot value dates. Free companion: GET /settlement-conventions. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.25 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.
Input Schema
{
"type": "object",
"properties": {
"trade_date": {
"type": "string",
"description": "Trade/reference date, YYYY-MM-DD. Day 0: never counted, never rolled."
},
"calendars": {
"minItems": 1,
"maxItems": 4,
"type": "array",
"items": {
"type": "string"
},
"description": "Calendar ids to intersect: two-letter ISO country codes, plus 'eu.t2' for the euro cash leg"
},
"business_days": {
"description": "The offset you are trading under (T+n)",
"type": "integer",
"minimum": 0,
"maximum": 30
},
"market": {
"description": "ISO country of the market whose cited cycle should apply (with instrument_class)",
"type": "string"
},
"instrument_class": {
"description": "Instrument class — a government bond never inherits an equity cycle",
"type": "string",
"enum": [
"cash_equity",
"etf",
"corporate_bond",
"government_bond",
"tbill",
"repo",
"primary_issuance",
"other"
]
},
"receipt": {
"default": false,
"description": "Default false. When true, a paid success includes an Ed25519 answer receipt (kind answer_receipt) at no extra USDC. Unpaid 402 and free refusals do not include one. Not a series certified extract (GET /v1/certified/{country}/{series} at $0.25; that SKU is not an MCP tool).",
"type": "boolean"
},
"api_key": {
"description": "API key (bypasses x402; metered for invoicing)",
"type": "string"
}
},
"required": [
"trade_date",
"calendars"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢compute_income_tax(country, taxable_income, receipt, api_key)
PAID ($0.05). Statutory income tax on a TAXABLE-income figure using the country's verified marginal bracket schedule, with full per-bracket workings, effective rate and marginal rate. Handles inflation-indexed tax units (Colombia UVT, Chile UTA, Peru UIT, Uruguay BPC) — you pass local currency. IMPORTANT: this is tax on taxable income, NOT net take-home pay — reliefs/allowances and social-security contributions are the caller's concern and are not applied (see the response scope_note). Pass api_key if you have one; otherwise the response explains how to pay via x402. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.25 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.
Input Schema
{
"type": "object",
"properties": {
"country": {
"type": "string",
"enum": [
"bs",
"ca",
"cr",
"do",
"gt",
"hn",
"mx",
"pa",
"sv",
"us"
],
"description": "ISO country code"
},
"taxable_income": {
"type": "number",
"description": "Taxable income in the country's local currency, in the schedule's own period basis (annual for most; monthly for Côte d'Ivoire, Uganda, Ethiopia, Costa Rica)"
},
"receipt": {
"default": false,
"description": "Default false. When true, a paid success includes an Ed25519 answer receipt (kind answer_receipt) at no extra USDC. Unpaid 402 and free refusals do not include one. Not a series certified extract (GET /v1/certified/{country}/{series} at $0.25; that SKU is not an MCP tool).",
"type": "boolean"
},
"api_key": {
"description": "API key (bypasses x402; metered for invoicing)",
"type": "string"
}
},
"required": [
"country",
"taxable_income"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢compute_statutory_interest(country, principal, days, from, to, ...)
PAID ($0.05). Simple statutory interest on a principal at the cited statutory-interest series rate: Actual/365 simple, principal × (rate/100) × (days/365). Pass days, or from and to as YYYY-MM-DD (from inclusive, to exclusive). If both are sent and disagree, the call is refused free. A series with no numeric rate after materialization (mechanism-only) is refused free — a non-answer is not sold. Not legal advice. Jurisdiction-specific compounding and day-count statutes are not applied. Pass api_key if you have one; otherwise the response explains how to pay via x402. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.25 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.
Input Schema
{
"type": "object",
"properties": {
"country": {
"type": "string",
"enum": [
"bs",
"ca",
"cr",
"do",
"gt",
"hn",
"mx",
"pa",
"sv",
"us"
],
"description": "ISO country code"
},
"principal": {
"type": "number",
"description": "Principal in the country's own currency. Must be a finite number greater than 0."
},
"days": {
"description": "Day-count days. Omit when from and to are set. If both are sent and disagree, the answer is refused free (HTTP 400).",
"type": "number"
},
"from": {
"description": "Period start, YYYY-MM-DD, inclusive. Pair with to. Day count is calendar days from inclusive to to exclusive (UTC dates).",
"type": "string"
},
"to": {
"description": "Period end, YYYY-MM-DD, exclusive.",
"type": "string"
},
"receipt": {
"default": false,
"description": "Default false. When true, a paid success includes an Ed25519 answer receipt (kind answer_receipt) at no extra USDC. Unpaid 402 and free refusals do not include one. Not a series certified extract (GET /v1/certified/{country}/{series} at $0.25; that SKU is not an MCP tool).",
"type": "boolean"
},
"api_key": {
"description": "API key (bypasses x402; metered for invoicing)",
"type": "string"
}
},
"required": [
"country",
"principal"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢compute_employment_cost(country, gross, period, subdivision, nationality, ...)
PAID ($0.10). Cost to employ: prices every statutory contribution on both the employee and employer sides for a gross salary, returning line-by-line amounts with instrument citations and an explicit refused list for schemes that could not be priced (unknown, not zero). Does NOT compute income tax — use compute_payroll for gross-to-net take-home where supported. Pass api_key if you have one; otherwise the response explains how to pay via x402. Optional receipt (boolean, default false): on a paid success, include an Ed25519 answer receipt at no extra USDC. An answer receipt is not a series certified extract (GET /v1/certified/{country}/{series} is $0.25 and is not an MCP tool) and is not legal advice. Verify with verify_answer_receipt against /certified/public-key.
Input Schema
{
"type": "object",
"properties": {
"country": {
"type": "string",
"enum": [
"ca",
"mx",
"us"
],
"description": "ISO country code with a costed contribution schedule"
},
"gross": {
"type": "number",
"description": "Gross pay in local currency"
},
"period": {
"description": "Period the gross covers (default month)",
"type": "string",
"enum": [
"month",
"year"
]
},
"subdivision": {
"description": "Optional ISO 3166-2 regional schedule (e.g. CA-QC, DE-SN)",
"type": "string"
},
"nationality": {
"description": "Gulf nationality for pension reach",
"type": "string",
"enum": [
"national",
"gcc",
"expat"
]
},
"contract": {
"description": "Contract type where rates differ",
"type": "string",
"enum": [
"indefinite",
"fixed_term"
]
},
"workplace_pension": {
"description": "Auto-enrolment / PPK participation (default true)",
"type": "boolean"
},
"childless_over_23": {
"description": "Germany care surcharge",
"type": "boolean"
},
"children_under_25": {
"description": "Germany per-child care reduction",
"type": "number"
},
"zusatzbeitrag_rate": {
"description": "Germany sickness-fund supplement",
"type": "number"
},
"receipt": {
"default": false,
"description": "Default false. When true, a paid success includes an Ed25519 answer receipt (kind answer_receipt) at no extra USDC. Unpaid 402 and free refusals do not include one. Not a series certified extract (GET /v1/certified/{country}/{series} at $0.25; that SKU is not an MCP tool).",
"type": "boolean"
},
"api_key": {
"description": "API key (bypasses x402; metered for invoicing)",
"type": "string"
}
},
"required": [
"country",
"gross"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡verify_answer_receipt(receipt, signature_value, public_key_pem, public_key_url)
FREE. Verify an answer receipt (kind answer_receipt) with the Ed25519 public key only. Pass the receipt object or its canonical JSON, signature_value when the signature is not inside the receipt, and public_key_pem to verify offline. If public_key_pem is omitted, the tool may GET signature.public_key (/certified/public-key) and read public_key_pem. Never send a private key. A valid signature shows this service issued that exact receipt. It does not turn the receipt into a series certified extract (GET /v1/certified/{country}/{series} at $0.25, not an MCP tool) and it is not legal advice. Same key and canonical-JSON rule as /certified/public-key.
Input Schema
{
"type": "object",
"properties": {
"receipt": {
"anyOf": [
{
"type": "string"
},
{
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
],
"description": "Answer receipt object (signature may be nested) or the canonical JSON of that object. A canonical JSON string of the signed body (signature omitted) is accepted when signature_value is also passed."
},
"signature_value": {
"description": "Base64 Ed25519 signature. Required when the receipt object or JSON string does not already include signature.value. Overrides a nested signature when both are sent.",
"type": "string"
},
"public_key_pem": {
"description": "SPKI public key PEM from GET /certified/public-key (field public_key_pem). Required for offline verify. A private key PEM is refused.",
"type": "string"
},
"public_key_url": {
"description": "Optional GET /certified/public-key URL used only when public_key_pem is omitted. Ignored when the PEM is present.",
"type": "string"
}
},
"required": [
"receipt"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}🟢get_snapshot(api_key)
PAID ($0.02). Snapshot of every series for every country in one call. Pass api_key if you have one; otherwise the response explains how to pay via x402. After a 200, bind get_changes (free poll) or register_alert (HMAC push; Register: $0 · Delivery after trial: $0.10) on this series so a later gazette does not silently retire the value.
Input Schema
{
"type": "object",
"properties": {
"api_key": {
"description": "API key",
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡get_changes(since)
FREE unmetered change + freshness feed. After any paid series or answer call, call this before you assume the cached value is still the law. Returns every series whose current value took effect on or after `since` (default last 30 days), newest first, each with last_confirmed and stale, PLUS a dataset-wide freshness summary: how many of the served series were re-verified within 1/7/30/90 days, how many are past their window, and which single series has gone longest without a check. Freshness is checkable or it is marketing. Args: since? (YYYY-MM-DD). Do not re-pay get_series to discover a diff. For a push bind, use register_alert (Register: $0 · Delivery after trial: $0.10). For a filing freeze of the current value, GET /v1/certified/{country}/{series} ($0.25).
Input Schema
{
"type": "object",
"properties": {
"since": {
"description": "YYYY-MM-DD. Omit for the server default (last 30 days). Free, unmetered.",
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡get_calendar(country, series)
FREE, unmetered. GET /v1/calendar for this brand's continent. Optional country (ISO 3166-1 alpha-2) and series. Derives reverify_by from last_confirmed + update_cycle_days (the same window that sets stale) and, only when current.effective_to is a non-empty string, next_effective_known with basis effective_to. status unknown omits that date. Never parses notes. Does not invent MPC, budget, or wage-review dates. next_effective_known is the recorded end of the current value, not a promised gazette event. A 402 is a gate bug — do not pay. Past changes stay on get_changes.
Input Schema
{
"type": "object",
"properties": {
"country": {
"description": "Optional ISO 3166-1 alpha-2. Omit for every series on this brand's continent. Unknown to the catalog is 404 free. Not two letters is 400 free.",
"type": "string"
},
"series": {
"description": "Optional series id (for example policy-rate). Omit for every series. A valid country with no match stays free.",
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}🟡register_alert(url, series, sources, api_key)
Bind a webhook so the next gazette does not silently stale a value you already paid for. REGISTERING IS FREE. Register: $0 · Delivery after trial: $0.10. First 3 deliveries are free; later deliveries are $0.10 and refunded if the webhook fails to send. HMAC-SHA256 signed. Two watch types on the same call: • series: ["za/vat-registration-threshold", "ke/*", "*"] → series.changed when the served value or its effective date moves. On usaref those watches are statutory (minimum-wage, income-tax, statutory-interest, sales-tax, public-holidays), not a FRED-macro subscription. • sources: ["<exact official source.url>"] → source.changed when the document BYTES change (old/new sha256 + citing series). Bytes ≠ value. Value changes arrive as series.changed. Unknown URLs refuse free (source_not_fingerprinted). Max 20 series + 20 sources. Required: url. Optional: api_key stored on the subscription to fund deliveries after the trial. This call does not meter that key. Prefer this over polling get_changes if you are a long-running agent. This is retention, not a new data product.
Input Schema
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Webhook endpoint that will receive HMAC-SHA256 signed events"
},
"series": {
"description": "Value watches, e.g. [\"za/vat-registration-threshold\", \"ke/*\", \"*\"]",
"maxItems": 20,
"type": "array",
"items": {
"type": "string"
}
},
"sources": {
"description": "Exact official-source URLs from a series source.url. Unknown URLs are refused free.",
"maxItems": 20,
"type": "array",
"items": {
"type": "string"
}
},
"api_key": {
"description": "Optional prepaid key stored on the subscription to fund deliveries after the trial. This call does not meter it.",
"type": "string"
}
},
"required": [
"url"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}Community
Evidence