htsapi.dev MCP server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| HTSAPI_KEY | No | Optional API key, only needed for the classify_product tool. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Official sources for US tariff classification: the Harmonized Tariff Schedule with its legal notes (USITC), CBP's rulings with their current status (CROSS), and what importers actually paid (Census). You classify; the importer decides. Work the way a licensed broker builds a classification file:
Facts first: what the product is, what it is made of (with percentages), how it works, what it is for, and how it is imported (set, kit, unassembled, packaging). If a fact that decides between headings is missing, ask for it rather than guess.
Candidate headings (GRI 1): heading terms and section and chapter notes decide, not titles or keywords. search_rulings shows how CBP classified similar goods: use it to find candidates, not to copy a code. lookup_hts_code reads the schedule: sections, a chapter's headings, a heading's subheadings.
Read the notes: get_notes for each candidate's section and chapter. Their exclusions and definitions override heading text and rulings alike. heading_scope with the product shows what CBP's rulings say each candidate heading covers, on the goods closest to it, and what they decided.
Only if several headings still fit: GRI 2 to 5 (3(b): essential character). Then go down one level at a time (GRI 6) with lookup_hts_code; an "Other" line says what it is not.
Check before relying on a code: rulings_under_code with the product (CODE IN DOUBT means CBP moved similar goods to another code), and get_ruling on each ruling you rely on: only a current ruling is authority (see superseded_by, modified_by, code_conflict, obsolete_codes, replaced_by).
Report the code, or the codes still open and the question that decides; the notes and GRIs applied; the rulings relied on and any against, by number and date. The classification_file prompt sets out the full file.
Cite rulings and notes only as a tool returned them, and say when you rely on your own knowledge. A ruling binds only its own goods: compare facts. low_match on a search means no close precedent. For goods to be entered, a code beyond 6 digits is the importer's decision (CBP HQ H350722); when it stays unclear, the importer can ask CBP for a binding ruling (19 CFR part 177).
Cost: general_duty is the schedule's base rate. importers_paid gives what importers from a country paid in the latest 3 Census months, base rate plus Chapter 99 duties (not anti-dumping or countervailing duties). It is history, not the duty owed today, which these tools do not compute.
classify_product (1 credit, needs an API key) is our own classifier: a second opinion after these steps, not a substitute for them. The other tools work without a key, 50 calls a day. Everything here is guidance, not a binding ruling.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
| prompts | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| lookup_hts_codeA | The tariff schedule, one level at a time, the way a classifier reads it. No code: the 22 sections and their chapters, for goods no ruling covers. A chapter (82) lists its headings with their legal text; a heading (8205) lists its subheadings in words; a subheading or line gives its path from the heading (an "Other" line says what it is not), base rates with the special-rate programs named, the 10-digit lines under it and the newest current CBP rulings under it. A code no longer in the schedule falls back to the nearest level that is. What importers paid is a separate tool, importers_paid. |
| importers_paidA | What importers from a country actually paid on a code in the latest 3 months Census has published: base rate plus Chapter 99 duties (Section 301, 232 and the like), as a percent of value, by month. Not the duty a shipment will owe today (Census is about 2 months behind and the rules change), and anti-dumping/countervailing duties are not included. For "what will this cost", not for classifying. |
| get_notesA | The legal text that decides between headings, from the official US schedule. With a code: its section's notes and its chapter's notes, subheading notes, Additional U.S. Notes and statistical notes. These have legal force (GRI 1): they exclude goods from a chapter ("this chapter does not cover...") and define terms. Without a code: the General Rules of Interpretation and the Additional U.S. Rules of Interpretation. The WCO Explanatory Notes are not included (copyrighted); heading_scope gives the passages CBP rulings quote from them. |
| heading_scopeA | What CBP's rulings quote and decide on a heading: for deciding whether a product falls in it.
Give the product to get what decides for it first. |
| rulings_under_codeA | Every CBP ruling that classifies goods under a code: for checking a code someone already
has. |
| search_rulingsB | CBP rulings for a product described in plain words, by meaning. Each ruling comes with
its HTS codes, its status (current, modified, superseded) and the product facts CBP
classified. |
| get_rulingA | One CBP ruling: its full text, HTS codes, status and, when revoked or modified, the ruling
that did it, the codes it moved the goods to, and the sentence that says so. Codes the
current schedule no longer has are listed in |
| classify_productA | Classify a product to a US HTS code. COSTS 1 CREDIT (refunded if it fails). Takes 10-60 s. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| classification_file | Classify one product for US import the way a broker documents it, and write the classification file: facts, headings considered, notes, GRIs, code, rulings, open points. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 8 tools
The two retrieval entry points are clearly distinguished (search_rulings by product meaning vs rulings_under_code by code), and get_ruling is a distinct single-record fetch. classify_product, lookup_hts_code and importers_paid are explicitly contrasted in their descriptions. The only soft overlap is get_notes vs heading_scope, which both surface legal notes applied to a heading/code, though one is statutory text and the other ruling-quoted explanatory passages.
All names use snake_case, which is consistent throughout. Most follow verb_noun (search_rulings, get_ruling, classify_product, lookup_hts_code, get_notes), with a few noun-phrase exceptions (importers_paid, heading_scope, rulings_under_code) that are still readable and self-descriptive.
Eight tools is well within the ideal range and each maps to a distinct step in the classification workflow: search, retrieve, classify, browse the schedule, read notes, read explanatory scope, check historical rulings, check duty paid. No tool appears redundant or filler.
The surface covers the full classification research loop from product description to code lookup to legal authority to real-world duty evidence. Minor gaps: there is no forward duty calculator or special-program/TRQ eligibility check, and AD/CVD is explicitly out of scope and has no tool, but agents can work around these via importers_paid and lookup_hts_code.