Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.closient.com/llms.txt

Use this file to discover all available pages before exploring further.

This page is the authoritative reference for the tools the Closient MCP server registers via tools/list. Every tool described here is a thin wrapper around the same service-layer functions used by the REST API — if a call would succeed via the REST API for the authenticated principal, it succeeds via MCP, and vice versa. For installation see Install the MCP Server. For error semantics see MCP Error Contract.

​
Conventions

  • GTIN inputs accept GTIN-8, GTIN-12, GTIN-13, or GTIN-14 with or without leading zeros. Closient normalizes everything to GTIN-14 internally — the normalized form is echoed back in the response.
  • Optional fields in the input schema default to None/null and are omitted from the resulting query when not supplied.
  • Errors are returned as JSON-RPC error objects with an RFC 9457 Problem Details payload in data. See MCP Error Contract for the code table.
  • Tool annotations (readOnlyHint, idempotentHint, etc.) are documented separately in MCP Tool Annotations.

​
ping

Health probe. Returns the string "pong". Useful from an agent preamble to verify the MCP connection is live before issuing real calls. Input: no arguments. Output: string — always "pong". Auth: none. Example: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "ping", "arguments": {} }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "content": [ { "type": "text", "text": "pong" } ] }
}

​
validate_gtin

Pure GTIN validation — check digit, length, format. No catalog lookup, no auth.
FieldTypeRequiredDescription
gtinstringyesA GTIN-8/12/13/14 string. Leading zeros are accepted but not required.
Output:
FieldTypeDescription
validbooleanOverall validity.
errorstring | nullHuman-readable reason if invalid.
normalizedstring | nullZero-padded GTIN-14 if valid.
lengthintegerOriginal GTIN length (before normalization).
Example: 
{
  "name": "validate_gtin",
  "arguments": { "gtin": "614141123452" }
}

{
  "valid": true,
  "error": null,
  "normalized": "00614141123452",
  "length": 12
}

​
resolve_gtin

Apply the GS1 Digital Link resolver-rule hierarchy and return the destination the resolver would redirect to for a given GTIN. Use this to learn what page (or external URL) a brand has configured for a product without actually following the redirect.
FieldTypeRequiredDescription
gtinstringyesA valid GTIN.
link_typestringnoGS1 link-type CURIE such as gs1:pip or gs1:recallStatus. When omitted, the default link-type rule wins.
Output:
FieldTypeDescription
destination_urlstringWhere the resolver would redirect.
destination_typestringHOSTED_PAGE or CUSTOM_URL.
fallback_appliedbooleantrue when no rule matched and the default was used.
product_foundbooleanWhether a Product row exists for the GTIN.
matched_rule_scopestring | nullPRODUCT, BRAND, ORGANIZATION, GLOBAL, or null.
Example: 
{
  "name": "resolve_gtin",
  "arguments": { "gtin": "00614141123452", "link_type": "gs1:pip" }
}

{
  "destination_url": "https://www.closient.com/01/00614141123452",
  "destination_type": "HOSTED_PAGE",
  "fallback_applied": false,
  "product_found": true,
  "matched_rule_scope": "PRODUCT"
}

​
lookup_product

Look up the structured catalog record for a GTIN. Returns found: false (rather than an error) when the GTIN is unknown so agents can branch on the boolean without try/except plumbing.
FieldTypeRequiredDescription
gtinstringyesA valid GTIN.
Output:
FieldTypeDescription
foundbooleanWhether the GTIN is in the catalog.
gtinstring | nullNormalized GTIN-14 if found.
namestring | nullProduct name.
brandstring | nullBrand name.
descriptionstring | nullProduct description.
data_sourcestring | nullOrigin of the record (manual, off, etc.).
metadataobjectFlat string-to-string developer metadata. {} when unset.
Example: 
{ "name": "lookup_product", "arguments": { "gtin": "00614141123452" } }

{
  "found": true,
  "gtin": "00614141123452",
  "name": "Sample Cereal",
  "brand": "Acme Foods",
  "description": "Whole-grain breakfast cereal.",
  "data_source": "manual",
  "metadata": { "internal_sku": "ACM-1234" }
}

​
search_products

Natural-language search across the Closient catalog. Combines pgvector semantic search with PostgreSQL full-text lexical search and (optionally) PostGIS-based geographic boosting.
FieldTypeRequiredDescription
querystringyesFree-text search string. Example: "organic oat milk".
filtersobjectnoFlat {key: value} dict applied to structured metadata. Useful keys: brand, category_id, country_of_origin.
geo_latnumbernoLatitude (WGS84) — requires geo_lng.
geo_lngnumbernoLongitude (WGS84).
limitintegernoMax results. Defaults to 20.
When both geo_lat and geo_lng are present, results within 50 km are boosted by proximity. Output:
FieldTypeDescription
itemsarrayOrdered by relevance (highest score first). Each item has gtin, brand, category, net_content, country_of_origin, price_min, price_max, score, distance_km.
totalintegerNumber of items returned.
querystringEcho of the input query.
Example: 
{
  "name": "search_products",
  "arguments": {
    "query": "gluten-free pasta",
    "geo_lat": 40.7128,
    "geo_lng": -74.0060,
    "limit": 5
  }
}

​
get_product_detail

Comprehensive product record — attributes, images, ingredients, nutrition facts. Use after search_products (or whenever a GTIN is already in hand) to fetch everything in one round-trip.
FieldTypeRequiredDescription
gtinstringyesA valid GTIN.
Output:
FieldTypeDescription
foundbooleanfalse for unknown GTINs; other fields are then null/empty.
productobject | nullCompact summary (gtin, name, brand, category, description, image_url, net_content, country_of_origin).
imagesarray{url, title, description, priority, is_primary} rows ordered by priority then creation time.
ingredientsarray{name, percentage_of_weight, priority} rows.
nutritionobject | null{serving_size, servings_per_container, label_format, nutrients: [{name, amount, unit, daily_value_pct}, ...]} or null.
hosted_page_urlstringThe canonical hosted-page path (/01/{gtin14}).

​
compare_products

Side-by-side comparison of 2-5 products by GTIN. Unknown GTINs appear as found: false columns rather than raising — partial comparisons are useful.
FieldTypeRequiredDescription
gtinsarray<string>yes2-5 GTINs. Order is preserved in the response.
Output:
FieldTypeDescription
itemsarrayOne column per requested GTIN — {found, gtin, product}.
attributesarrayAligned attribute rows — {name, values} where values[i] corresponds to items[i]. Currently: brand, category, net_content, country_of_origin, price_min, price_max.
Example: 
{
  "name": "compare_products",
  "arguments": { "gtins": ["00614141123452", "00614141999999"] }
}

​
check_availability

Find nearby physical stores carrying a specific product. Returns active in-store offers within radius_km, ordered by ascending distance. When no offers exist for the product, the response is structurally well-formed (empty locations) rather than an error so agents can confidently say “no nearby availability” without exception handling.
FieldTypeRequiredDescription
gtinstringyesA valid GTIN.
latnumberyesLatitude (WGS84) of the search origin.
lngnumberyesLongitude (WGS84).
radius_kmnumbernoMaximum search radius in km. Defaults to 25.
Output:
FieldTypeDescription
gtinstringNormalized GTIN-14 echoed for convenience.
radius_kmnumberEcho of the search radius.
locationsarray{retailer, store_name, address, city, region, postal_code, distance_km, price, currency, inventory_status} rows.
totalintegerNumber of locations returned (may be 0).

​
generate_qr_url

Build the canonical GS1 Digital Link URL for a GTIN, optionally with batch/lot and serial qualifiers. The returned URL is what should be encoded into a 2D barcode (QR or Data Matrix). When scanned, the URL hits Closient’s resolver at /01/{gtin14}[/10/{batch}][/21/{serial}] and returns the linkset or redirects to the destination per the resolver rules.
FieldTypeRequiredDescription
gtinstringyesA valid GTIN — normalized to GTIN-14 in the URL.
batchstringnoBatch / lot identifier (GS1 AI 10).
serialstringnoUnique serial (GS1 AI 21).
Output:
FieldTypeDescription
qr_urlstringThe canonical Digital Link URL.
gtin14stringNormalized GTIN-14 used in the URL.
hoststringHost portion of the URL (from SITE_URL).
Auth: OAuth 2.0 bearer token with qr:generate scope. See Authentication. Anonymous calls and calls with a token that doesn’t include qr:generate return JSON-RPC error code -32002 (forbidden). Example: 
{
  "name": "generate_qr_url",
  "arguments": {
    "gtin": "00614141123452",
    "batch": "LOT-A1",
    "serial": "SN-0001"
  }
}

{
  "qr_url": "https://www.closient.com/01/00614141123452/10/LOT-A1/21/SN-0001",
  "gtin14": "00614141123452",
  "host": "www.closient.com"
}

​
See also