The reference layer, documented

The full MCP server reference — all 25 tools, the response envelope, rate limits and directory listings — lives on its own page.

After saving the config, fully quit and relaunch your MCP client (Claude Desktop, Cursor, Cline). MCP servers are only loaded at client startup — editing the config in a running session does nothing until restart.

Confirm the FreightUtils MCP surface is reachable before asking your agent any freight question:

A 200 response with "status":"ok" and "tools_registered":25 means the remote MCP surface is live. The endpoint is callable by your agent too — Claude/Cursor/Cline can hit it for a self-diagnostic without you having to open a terminal.

// FreightUtils API — JavaScript example
// Calculate loading metres for 10 Euro pallets

const response = await fetch(
  'https://www.freightutils.com/api/ldm?pallet=euro&qty=10'
);
const data = await response.json();

console.log(`LDM: ${data.ldm}`);
console.log(`Utilisation: ${data.utilisation_percent}%`);
console.log(`Fits: ${data.fits}`);

All endpoints work the same way. No auth, no signup. Full reference below ↓

Composite endpoint that chains CBM, chargeable weight, LDM, ADR compliance, and UK duty/VAT estimation into a single call. Accepts a unified Shipment object and returns comprehensive results based on transport mode.

Mode Parameter

Unknown fields are refused, never ignored. A key the summary does not read — in the body, on an item, in origin / destination or in options — is refused with HTTP 400 naming it, and so is one field sent under two names (un_number and unNumber). Dropped, a line’s un: "1051" made it an ordinary line and the dangerous-goods check never saw a transport category 0 substance.

Per piece or per line. weight and customs_value are per item — each is multiplied by the line’s quantity (the response echoes customs.customsValueBasis and customs.customsValueTotal). adr_quantity is the total for the whole line, all pieces together, and is never multiplied (compliance.adrFlags.adrQuantityBasis: "line_total"). The suggested vehicle must hold the load by its own record — length, payload and pallet capacity — and trailerUtilisation is of that vehicle (utilisationBasis names it); the suggested container is the smallest dry box whose record holds the volume and payload.

Money is 0 or more. freight_cost, insurance_cost and each item’s customs_value must be a finite number of 0 or more; left out, null or blank means none. A negative, NaN or infinite value is refused with HTTP 400 naming the field — a negative freight cost used to come off the CIF value and the UK duty estimate with it.

Example Request

Mixed 3-item road shipment with a DG item and HS code:

Example Response

Pro-tier endpoint. Free access: 25 requests/day anonymous, 100/day with a free API key. Subscribe for higher limits.

Calculate the loading metres (LDM) required for a consignment on a UK/EU road freight trailer.

Parameters

* Either pallet (preset ID) or both length and width must be provided.

Example Requests

12 Euro pallets on an artic:

Custom dimensions, stackable, with weight check:

cURL example:

US 53ft trailer:

Response

Calculate the cubic metre (CBM) volume of a shipment. Returns total CBM plus equivalents in cubic feet, litres, and cubic inches.

Parameters

Example Request

5 boxes, 120×80×100 cm each:

Estimate freight transport CO2e using the ISO 14083 / GLEC distance-based method: emissions = mass × distance × an open emission-intensity factor (kgCO2e/tonne-km). Provide actual gross mass, not chargeable/volumetric weight (a common air-freight mistake — see mass_basis). Returns well-to-wheel and tank-to-wheel emissions, the exact factor used, and a _source citing both the method and the specific open factor (DEFRA / EPA / ADEME). Each result also carries empty_running (the fleet-average factor already includes average empty running — don't double-count an empty return), representativeness (sea/air = low, high real-world variance), a human-readable summary, and _source.factor.last_verified. You provide the distance — this endpoint does not route. Best-effort estimate, not a verified carbon report; an unknown mode/sub_mode/region returns available:false with the covered options.

Parameters

Example Request

10 tonnes by road, 500 km, UK (DEFRA), well-to-wheel:

Parse an arbitrary string (e.g. a booking line or email) to find and validate every freight identifier in it — shipping container (ISO 6346), air waybill (IATA modulus-7) and IMO ship number — or validate a single identifier by type. Returns per identifier: type, normalised form, valid (pass/fail), expected vs actual check digit, details (container owner/category; the AWB airline, or airline_candidates when the prefix is held by more than one record; IMO number) and a _source. Structural only — a valid check digit means well-formed, not that the entity exists.

Parameters

*Provide text (parse mode) OR value+type (typed mode).

Example Request

Parse a mixed string:

Check a goods description against the official EU ICS2 stop-words list (unacceptable/vague terms for entry summary declarations). Returns the flagged terms — each with a note on whether it is the standalone description (automatic ENS rejection) or embedded (make the description more specific) — a clean boolean, a caveat, and a _source citing the EU list + legal basis. Reference only: not an ENS filing, not a compliance determination; the list is non-exhaustive and clean does not guarantee acceptance. No accepted/rejected verdict. The submitted description is not persisted or logged (response is no-store).

Parameters

Example Request

A vague standalone description:

Look up an airport by IATA code (3 letters), ICAO code (4 chars), or free-text name / city search. Provide one of iata, icao or q. Returns the full record (both codes, name, type, municipality, region, country, coordinates, elevation); ambiguous name searches return ranked candidates. Optional type filter. Data: OurAirports (public domain), cross-checked vs OpenFlights + Wikidata. Reference only — not for navigation; verify current codes with IATA/ICAO.

Parameters

Example Request

Find the airports nearest to a caller-provided latitude/longitude, sorted by great-circle (haversine) distance with distance_km on each result. Coordinates are input only — never stored or logged. Optional radius_km, max_results (1–50, default 10) and type filter. Does NOT geocode place names or compute routes — pass coordinates you already hold.

Parameters

Example Request

The agent front door: one identifier-ish string in, typed, ranked, cited candidates out — without needing to know which lookup endpoint fits. Thirteen grammars all run on every query: UN numbers, AWB prefixes, airline IATA/ICAO, airport IATA/ICAO, UN/LOCODE, ISO 6346 container numbers (check digit computed), HS codes, Incoterms, ADR tunnel codes, ULD serials and ISO container size/type codes. Ambiguity is the product: colliding grammars return multiple candidates with an inspectable rank_basis on each, never a silent guess. Zero candidates is a validcount: 0 result — never an error. v1 resolves a single token (max 32 chars); free-text extraction is out of scope. This endpoint is envelope v1.1 native — responses are always enveloped; pass ?envelope=1 for the byte-stable v1 envelope.

Parameters

Example Request

Response Fields (per candidate)

Calculate air freight chargeable weight — whichever is higher between actual gross weight and volumetric (dimensional) weight. Supports custom volumetric factors for all carriers.

Parameters

Example Request

2 pieces, 120×80×100 cm, 500 kg total, IATA factor:

Calculate how many boxes fit on a pallet using a layer-based algorithm. Returns boxes per layer, number of layers, total boxes, orientation used, and volume/weight analysis. Optional weight constraint caps the result at the pallet's maximum payload.

Parameters

Example Request

Look up ADR 2025 dangerous goods by UN number, search by substance name, or filter by hazard class. The dataset contains 2,939 entries from the ADR 2025 Dangerous Goods List (Table A). Responses are cached for 1 hour (s-maxage=3600).

Query Modes

Provide exactly one parameter per request. Omitting all parameters returns a 400 with usage hints.

Example Requests

Exact UN number lookup:

Per-row verification: every row carries verified and a verification block, always. verified: true (status verified, basis row) only where the row itself was audited field by field against the purchased UNECE Table A — then audited_at, the cited source count and the row’s sources[] ride along (56 anchor rows today, e.g. UN 1845, UN 1789). Every other row says verified: false with the reason no row-level audit: it was transcribed from the same Table A and is held by the dataset-level checks only. The envelope’s _source.provenance_status is the dataset-level claim; the row field is the row’s own. Silence is never verification.

Scope-flagged rows: 28 Table A entries carry a scope remark instead of a packing group. Those return packing_group: null plus not_subject_to_adr: true(with conditions_ref, e.g. "5.5.3" for UN 1845 dry ice) orcarriage_prohibited: true, and table_a_remark preserves the verbatim Table A text.

Search by substance name:

Filter by hazard class:

Calculate whether the ADR 1.1.3.6 small load exemption applies to dangerous goods carried in packages (1.1.3.6.2 — not goods in bulk or in tanks; the calculator takes no packaging input). Supports single-substance GET queries and multi-substance POST requests. Checks the 1.1.3.6.4 points total (1,000) and the 1.1.3.6.3 maximum for each transport category — a total on the vehicle when every line is in the same category. Every line comes back with a state naming its route: COUNTED, AIR_ONLY_ID, NOT_SUBJECT_TO_ADR or BLOCKED.

GET — Single Substance

Example — 200 litres of petrol:

POST — Multi-Substance Load

Request body:

Response structure is identical to the GET endpoint, with multiple items in the array.

Inputs are never coerced. Every quantity must be a JSON number greater than 0 and at most 1,000,000,000 (GET qty: digits, e.g. 200,0.5 or 5e-7). Text such as "300 kg", null,0 or a negative value is refused with HTTP 400 naming the value received — one bad line refuses the whole request, and no points are ever computed from it. unit accepts onlyL or kg, basis only net or gross,packing_group only I/II/III, andvariant_index only a whole number (a blank or false no longer means row 0); a GET parameter sent twice is refused. When every line is in the same transport category, the column (3) maximum is checked against the total on the vehicle (1.1.3.6.3), not line by line. Every field of a line — un_number, quantity, packing_group, variant_index, unit, basis — goes on that line in a POST: sent at the top level beside items[] it is refused with HTTP 400 naming the field (a substance as an item of its own) — never dropped, and never applied to a line by guess.

Unknown fields are refused, never ignored. A key the calculator does not read — on an item, beside items[], or as a GET parameter — is refused with HTTP 400 that names it, suggests the accepted name it most likely meant and lists the accepted ones. Field names are exact: quantity_basis (the name the answer echoes), Unit or UN_NUMBER used to be dropped without a word, so a declaration under the wrong name — gross, kilograms, a second substance — changed nothing and the load could read exempt. Accepted on an item: un_number, quantity, packing_group, variant_index, unit, basis; GET parameters: un, qty, unit, basis, packing_group, variant_index, plus envelope. Send the API key in the X-API-Key header. The same rule holds on /api/adr/lq-check, /api/shipment/summary and the MCP tools.

Multi-variant UN numbers: some UN numbers have more than one ADR Table A row (different packing groups / concentration bands with different transport categories — e.g. UN 1789 PG II vs PG III). Pass an optional packing_group(I/II/III, GET query or per item) or variant_index(from /api/adr) to pin one row. Without one, the response is HTTP 200 with blocking_errors[AMBIGUOUS_UN_VARIANT], human_review_required: true and a candidates[] list (no verdict) rather than a silently-guessed row — the code is in the plain body as well as the envelope. Its recovery names the line’s item_index and the fields that choose a row (packing_group or variant_index), and never chooses one itself: its params repeat your call without a row, so sent unchanged they are asked again. Pick the row from candidates[] by the goodsrow from candidates[] by the goods’ own packing group or concentration, never byrsquo; own packing group, concentration or description, never by its position in the list. A packing_group that still leaves several rows is enough when those rows agree on class, transport category, scope and the 1.1.3.6.3 counted dimension (UN 1790 PG I: two concentration bands, both category 1) — the verdict is returned with items[].equivalent_variants and avariant_note saying which rows it holds for; only when the rows disagree(UN 2215 PG III: MOLTEN is category 0, the solid category 3) does it still ask for variant_index, and then candidates[] lists only that packing group’s rows. In a mixed load, an unpinned multi-variant line is withheld on its own (items[].withheld: true, points null) while every other line keeps its points; total_points is null until it is pinned, because 1.1.3.6.4 sums every line, and exempt is null too unless the resolved lines alone already disqualify the load — a “CARRIAGE PROHIBITED” entry, a category 0 entry, a per-substance maximum exceeded, or a partial sum already over 1,000 — in which case exempt is false with the usual message (and carriage_prohibited: true where that is the reason), since no packing group can undo those. candidates[] carry expected_unit, the 1.1.3.6.3 counted dimension — for UN 3375 PG II (liquid in L, solid in kg) that is the only field on which the rows differ. Only a load in which every line is ambiguous returns the no-items candidates[] shape.

Response Fields

Scope verdicts: 28 ADR 2025 Table A rows carry a scope remark instead of a packing group. A load of such entries never enters the 1.1.3.6 points math — e.g.?un=1845&qty=100 (dry ice) returns not_subject_to_adr: true withmessage “Not subject to ADR (road). Section 5.5.3 applies: …” and the verbatim 5.5.3 conditions, while a “CARRIAGE PROHIBITED” entry (e.g. UN 0020) returns exempt: false with carriage_prohibited: true. An ID-prefixed air-only number (e.g. ID 8000, consumer commodity) has no ADR Table A entry and so gives no transport category: its line is AIR_ONLY_ID and adds nothing to the points, with a warning stating the condition that rests on — it is the ADR answer when the packages are limited quantities to the ICAO Technical Instructions (3.4.9 and 3.4.10 deem them to meet 3.4.1–3.4.4, and goods exempted under 1.1.3.4.2 are not taken into account by 1.1.3.6.5); goods not in such packages must be entered under their own UN numbers. A load of nothing else scores 0 with its own message — never “1.1.3.6 exemption applies”, and never “not subject to ADR”, which is a Table A remark an ID number does not have. Only the ID prefix makes a line air-only.

Check whether dangerous goods qualify for ADR Limited Quantity (Chapter 3.4) or Excepted Quantity (Chapter 3.5) concessions. Accepts up to 20 items per request and returns per-item pass/fail status against ADR Table A limits.

Request Body

A UN number that resolves to more than one ADR Table A row without a packing_group/variant_index returns HTTP 200 with human_review_required: true and a candidates[] list (no verdict) rather than checking a silently-guessed packing group. A packing_group that still leaves several rows is enough when those rows agree on class, column (7a), column (7b) and scope (UN 1790 PG I: two concentration bands, both LQ 0 / E0) — the item is answered with equivalent_variants and a variant_note; only when the rows disagree does it still ask for variant_index, listing only that packing group’s rows. In a batch, an unpinned multi-variant line is withheld on its own(status: "withheld", row fields null) while the other lines are answered;overall_status can never read qualifies while a line is withheld, andcandidates[] carries that line’s rows tagged with its item_index. Only a batch in which every line is ambiguous returns the no-items shape; it then carries blocking_errors[AMBIGUOUS_UN_VARIANT], one per line, in the plain body as well as the envelope, whose recovery names the line’s item_index and the fields that choose a row and never chooses one — its params, sent unchanged, are asked again.

Unknown fields are refused, never ignored. Only the fields above are read; any other key — on an item (inner_packagings, units), at the top level (Mode, or inner_packaging_qty beside items[]) or in the query string — is refused with HTTP 400 naming it and suggesting the accepted name. Dropped, a count of 20 inner packagings fell back to one and an EQ check read qualifies where 20 × 30 ml is over E2’s 500 ml per outer packaging.

Example — check LQ for 0.5 L of petrol:

Response Fields

Search airlines by name, IATA code, ICAO code, AWB prefix, or country. The dataset contains6,356 airlines including 392 cargo airlines with AWB prefixes.

Query Modes

Example Requests

AWB prefix lookup:

IATA code lookup:

Name search:

Response Fields

Verification status, and what it changes in the envelope

The airline dataset is still pending-verification, but individual records now carry their own evidence. active_verified means every identifier this API serves for that record — IATA code, ICAO code, AWB prefix — was confirmed against a page the carrier itself publishes (ICAO designator and callsign against FAA Order JO 7340.2), with the exact URL and access date in field_provenance. Aggregator and directory sites are scored at zero and never appear as evidence.historical means the carrier demonstrably ceased operating; the codes are kept as historical fact and may since have been reassigned. unverified means we looked and the evidence did not clear that bar — the honest default, not a slur on the record.

This is load-bearing in the envelope: an answer whose records are all active_verified is emitted at confidence.level: "high" with no advisory. Any other mix — one unverified record, one never-audited record, or an empty result — falls back to medium plus the PROVENANCE_PENDING warning. The lift is earned per answer and derived from the records in it, so it can never claim more than the evidence behind it.

Responses also carry a top-level _source citability envelope and a meta block whose airlines count is derived from the dataset at build time — never hand-typed.

Look up INCOTERMS 2020 trade terms. Returns all 11 terms by default, or filter by code or transport category. Each term includes seller/buyer responsibilities, risk and cost transfer points, insurance obligations, and practical guidance.

Parameters

Omit all parameters to return all 11 INCOTERMS 2020 terms.

Example Requests

Single term lookup:

Filter by transport category:

All terms:

Shipping container specifications — internal/external dimensions, weights, door openings, and pallet capacity for all 10 standard ISO container types. Optionally calculate how many items fit in a specific container.

Query Modes

Example Requests

List all containers:

Single container specs:

Loading calculation — how many 60×40×40cm boxes fit in a 40ft HC:

Convert between freight-relevant units — weights, volumes, lengths, and freight-specific conversions (CBM to chargeable weight, CBM to freight tonnes).

Parameters

Supported Unit Codes

Example Requests

Standard conversion:

CBM to chargeable weight (IATA 6000 divisor):

CBM to freight tonnes (W/M rule):

Search and browse Harmonized System (HS 2022) commodity codes. Supports text search by product description, exact code lookup with ancestor chain, and section browsing. Covers all 6,937 codes across 21 sections and 97 chapters.

Query Modes

Provide exactly one parameter per request. Omitting all parameters returns a 400 with usage hints.

Example Requests

Search by description:

Code lookup with ancestors:

Browse section:

Calculate total CBM, loading metres (LDM), volumetric and mode-specific chargeable weight across a multi-item mixed consignment — per-line and grand totals, plus objective advisory flags (implausible density, mode/option mismatch, dangerous-goods presence by UN number against the ADR 2025 reference, and ISO 6346 container / IATA AWB check-digit validity). Supports sea, air, and road modes. Canonical request/response schema: consignment.v1.json.

Best-effort deterministic calculation and reference data only. Verify all inputs. Not regulatory, customs, or dangerous-goods compliance advice — you remain responsible for classification, documentation and carrier acceptance.

Request Body (JSON)

Canonical Line Object (lines[])

Example Request

Estimate UK import duty and VAT for a commodity code using live GOV.UK Trade Tariff data. Accepts customs value, origin country, freight/insurance costs, and INCOTERM for CIF adjustment.

Request Body (JSON)

Example Request

A response from production on 2026-10-08 (live rates move). Send 610910 instead and the answer is a 400 naming 6109100010 (T-shirts) and 6109100090 (Other) in declarable_codes.

Search and look up UN/LOCODE transport locations — 116,232+ seaports, airports, rail terminals, inland depots, and border crossings worldwide. Responses are cached for 24 hours.

Query Modes

Example Requests

Search by name:

Exact code lookup:

Filter by country and function:

Look up air freight Unit Load Device (ULD) specifications. 16 types including LD3 (AKE), PMC main deck pallet, temperature-controlled containers, and more. Returns dimensions, weights, volume, and aircraft compatibility.

Parameters

An unrecognised query parameter returns 400 naming it, rather than being ignored — a filter this endpoint does not understand must never come back looking like a successful unfiltered query.

Example Requests

Single ULD lookup:

Filter by category:

All ULD types:

Look up road freight vehicle and trailer specifications. 17 types covering articulated trailers, rigid trucks, and vans. Returns internal dimensions, payload limits, pallet capacity, and features.

Values carry their own semantics rather than leaving you to infer them. internal_dimensions.height is null on open-deck vehicles (flatbed, low-loader) — never 0, which would make a length × width × height calculation return zero volume. height_basis says what a null means (unbounded-open-top — no roof, so no constraint exists; varies-by-configuration; or unverified — a constraint exists but no trustworthy figure is held), and open_top states the physical fact separately. pallet_capacity_basis says whether a pallet count is floor geometry (floor-positions), capped by payload (weight-limited), an industry-convention figure, or unverified — which matters, because a floor-derived count and a payload-capped count are very different answers. max_pallet_height_mm gives the per-deck clearance on multi-deck vehicles and is null elsewhere, where the internal height is the usable clearance.

Parameters

Example Requests

Single vehicle lookup:

Filter by category:

Filter by region: