tilwhen

MCP server: verifiable date answers

Date arithmetic is a place where a model sounds most confident and is most often wrong: business days across a public holiday, a due date that moved because it landed on a Sunday, a countdown computed in the wrong timezone. The failure is silent, because a plausible date looks exactly like a correct one.

This server answers those questions through the same engine that powers tilwhen.com and its REST API, and returns the working alongside the answer, so a client can show its reasoning or a reader can check it.

Connect

Hosted at https://mcp.tilwhen.com/mcp. Nothing to install, clone or build, and no API key: it is a public read-only endpoint over Streamable HTTP.

Claude Code:

claude mcp add --transport http tilwhen https://mcp.tilwhen.com/mcp

Claude Desktop, Cursor, or any client using the standard JSON config:

{
  "mcpServers": {
    "tilwhen": {
      "url": "https://mcp.tilwhen.com/mcp"
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "tilwhen": {
      "type": "http",
      "url": "https://mcp.tilwhen.com/mcp"
    }
  }
}

Prefer plain HTTP? The REST API answers the same questions with the same receipts and no client library.

Tools

ToolWhat it doesREST equivalent
parse_date_query Parses queries like "90 business days from today in uganda" into a normalized operation, answers it, and returns the auditable receipt. Ambiguous dates (03/04/2027) return needsClarification instead of a guess. /api/v1/parse
add_days The date N whole calendar days after a date (exclusive counting: the start date is day 0). /api/v1/add
subtract_days The date N whole calendar days before a date. /api/v1/subtract
days_between Signed whole calendar days from one date to another, midnight to midnight, endpoints exclusive (the gap). /api/v1/diff
business_days Span mode (from+to): business days between two dates, exclusive of the start day, inclusive of the end day. Add mode (days, optional date): the date N business days away. Optional holiday jurisdiction or custom calendar, and a selectable working week. /api/v1/business-days
invoice_due Due date for Net-N payment terms (calendar days, invoice date = day 0). Optional roll-forward past weekends and, with a jurisdiction or custom calendar, public holidays. /api/v1/invoice-due
next_occurrence The next occurrence strictly after the base date (default today) of either a tracked event slug (e.g. "christmas") or a weekday (0 = Sunday .. 6 = Saturday). Provide exactly one of event/weekday. /api/v1/next-occurrence
holidays Observed public holidays with the nominal (legal) date and status: rule (statutory) or declared (officially declared for that year). Declared-only holidays are omitted for undeclared years, with a holiday_data_incomplete warning. /api/v1/holidays
explain Runs any operation and returns the receipt plus human-readable derivation steps. Accepts the same fields as the other tools, discriminated by op. /api/v1/explain

Resources

Read these to ground an answer in the method rather than guessing at it.

URIContents
tilwhen://methodology Counting convention, business-day semantics, and citation guidance
tilwhen://jurisdictions Jurisdiction ids, labels, sources, and declared-data coverage
tilwhen://limitations What this server deliberately does not do

Example prompts

  • "How many business days between 12 July and 25 December 2026, excluding UK bank holidays? Show the receipt."
  • "An invoice dated today on Net 45 terms, rolled forward past US federal holidays. What date is it due?"
  • "List Scotland's public holidays for 2027 and tell me which ones are substitute days."
  • "What does '90 business days from today in Uganda' resolve to, and which holidays did you exclude?"

What a receipt contains

Every tool answers with structuredContent holding the answer and its receipt: the normalized operation, the pinned input dates, the IANA timezone, the counting convention (whole calendar days, today = day 0, exclusive), the working week, the holiday calendar with each excluded holiday itemised, the primary sources with retrieval dates, the engine and holiday-dataset versions, and a stable result ID. The ID is a deterministic hash of the normalized inputs and versions with the timestamp excluded, so the same question under the same versions always reproduces the same ID. Currently engine 1.0.0, holiday dataset 2026.07.2. See how to cite a result.

Security model

Pure computation over bundled data. No shell, no eval, no file reads, no outbound network calls, and no unbounded loops: every input is bounded by the engine limits. It is read-only and stateless, so there is no session, no stored data and nothing a request can mutate; every tool is annotated readOnlyHint and idempotentHint so your client can call it without prompting you each time. It never reads the server's timezone either, because tz is an explicit input defaulting to UTC, so the same call always gives the same answer. Nothing you send is stored or logged as content.

Holiday calendars and limits

Jurisdictions: United States, United Kingdom (England & Wales), United Kingdom (Scotland), United Kingdom (Northern Ireland), Ireland, France, Canada, Australia, Uganda, plus a caller-supplied custom calendar. There is deliberately no default: omit the jurisdiction and no holidays are excluded, and the receipt says so rather than inferring one from a timezone. Holidays whose date is declared per year rather than fixed by rule are included only for officially declared years; a span crossing an undeclared year returns a holiday_data_incomplete warning instead of an estimate.

Missing a jurisdiction you need? Tell us which one.