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/nulland 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:
validate_gtin
Pure GTIN validation — check digit, length, format. No catalog
lookup, no auth.
Output:
Example:
validate_digital_link
GS1 Digital Link conformance check. Grades a URI against the spec and
returns every issue found, plus the parsed primary key, qualifiers and
data attributes. No catalog lookup, no auth. The same engine backs the
keyless HTTP endpoint GET /resolver/api/v1/public/gs1/validate.
Output:
A non-conformant URI is a normal result with
is_conformant: false, not
an error. An empty or over-long uri returns error -32101.
Example:
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.
Output:
Example:
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.
Output:
Example:
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.
When both
geo_lat and geo_lng are present, results within 50 km
are boosted by proximity.
Output:
Example:
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.
Output:
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.
Output:
Example:
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.
Output:
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.
Output:
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:
ops_snapshot
Read the Closient staff ops snapshot: the ops dashboard’s metrics in six
sections (resolver, safety, business, pipeline, platform and engineering),
each metric naming its source and when it was measured. It takes no arguments and reads a cached snapshot, so
repeated calls are cheap.
Output: the snapshot object — generated_at, environment,
cache_seconds and sections[] (each with key, title and metrics[]).
Every metric carries a status:
Auth: OAuth 2.0 bearer token with the
ops:snapshot scope, issued to a
Closient staff member. The scope is granted only to staff (see
Authentication); a token without it, or one
whose user is no longer staff, gets JSON-RPC error code -32002
(forbidden).
Example:
Product write tools
Every tool in this section requires an OAuth 2.0 bearer token issued via theauthorization_code grant (an end-user token — client_credentials
tokens have no user to attribute writes to and are rejected). The caller
must additionally hold organization membership with the permission noted
per tool: CONTRIBUTE (OWNER, MANAGER, or EDITOR role) for most tools, or
OWNER/MANAGER specifically for create_product. See
Authentication for the OAuth flow and
MCP Identity Propagation for how the acting user is
threaded through to the audit trail.
Three scopes gate this family: account:write (create_organization),
products:write (create_product, update_product) and dashboard:write
(everything else — images, documents, videos, nutrition, ingredients).
create_organization
Set up the caller’s first organization, with the caller as its owner. A
person who has just signed in to connect Closient belongs to no
organization, so create_product refuses them with -32002 and points
here. Once the organization exists, the same connection can call
create_product and generate_qr_url with no reconnect: a login approved
while you belonged to no organization acts on the one organization you then
create.
Output:
{organization_id, name, country, is_brand, role}.
organization_id is the 22-character public identifier create_product
accepts, and role is owner. The organization starts on the free plan;
nothing is charged.
Errors: a name another organization already carries (case and spacing
ignored) is -32201 conflict. A caller who already belongs to an
organization is -32201 naming it, so a retried call never makes a twin;
add further organizations on the website. A login approved for one
specific organization is -32002: it acts only on that organization, so
reconnect to create a new one.
Auth: account:write scope, end-user (authorization_code) token.
Example:
create_product
Create a new product and claim it for an organization — the first step of
brand-owner product entry for a GTIN not yet in Closient’s catalog.
Output: compact product summary —
{gtin, name, brand, category, description, image_url, net_content, country_of_origin}, plus
unverified_disclosure while the product has no verified prefix claim, which
is how every new product starts. See Unverified products.
Auth: products:write scope; caller must be OWNER or MANAGER of the
target organization.
Unverified products
create_product, generate_qr_url and POST /products in the REST API
return an unverified_disclosure field until a reviewer verifies the
product’s prefix claim. It reads:
No verified prefix claim exists for this product, so Closient treats it as unverified. Until a reviewer verifies the claim, an anonymous scanner sees only what Closient can state on its own authority: the GTIN, the decoded prefix and the GS1 licensing member organization, the parsed application identifiers with their safety verdict, recall status, Digital Link conformance, and the licensee name GS1 lists for the prefix. Everything the claimant supplied (name, description, images, ingredients, certifications, brand links and the organization name) is withheld from anonymous visitors until verification. Members of the owning organization still see the full page. To start or continue verification, use the claim verification tools: get_claim_verification, submit_claim_evidence, check_claim_dns and check_claim_http.
update_product
Update basic info, structured net content, dimensions/weight, or GPC
classification on a claimed product — all share a single field allowlist
(Product.BRAND_EDITABLE_FIELDS), so one tool covers all three.
Output: compact product summary (same shape as
create_product).
Auth: products:write scope; caller needs CONTRIBUTE permission on the
owning organization.
Example:
upload_product_image
Upload an image and attach it to a claimed product.
Output:
{id, url, title, is_primary, priority}.
Auth: dashboard:write scope; caller needs CONTRIBUTE permission.
delete_product_image
Delete an image from a claimed product. Immediate and permanent.
Output:
{deleted: true, image_id}.
upload_product_document
Upload a PDF (spec sheet, safety data sheet, certificate) and attach it to
a claimed product. Non-PDF content is rejected. Dispatches an async
metadata/thumbnail extraction task; the response reflects the upload
itself, not the enrichment (visible on a subsequent get_product_detail).
Output:
{id, url, title, description, file_size_bytes}.
update_product_document
Partially update a document’s title/description, and optionally replace
its file, on a claimed product.
Output:
{id, url, title, description, file_size_bytes}.
delete_product_document
Delete a document from a claimed product. Immediate and permanent.
Output:
{deleted: true, document_id}.
add_product_video
Attach a YouTube video link to a claimed product. YouTube only — Closient
does not host video files.
Output:
{id, youtube_url, video_id, title, description, priority}.
update_product_video
Partially update a video attached to a claimed product.
Output: same shape as
add_product_video.
delete_product_video
Delete a video from a claimed product. Immediate and permanent.
Output:
{deleted: true, video_id}.
set_product_nutrition
Create or wholesale-replace a product’s entire nutrition-facts panel —
the header plus every nutrient row — in one call. Reconciles nutrients
against what’s already stored by nutrient_type: matched rows are
updated, new types are created, and rows omitted from this call are
deleted. This is not a merge/patch operation — always pass the complete
label.
Output:
{serving_size, servings_per_container, label_format, nutrients: [{nutrient_type, amount, unit, daily_value_pct}, ...]}.
Example:
set_product_ingredients
Set a product’s ingredient statement from raw label text — Closient parses
it into structured substance mentions automatically (splitting out a “may
contain” / cross-contamination section, resolving each mention to a known
substance where possible). Wholesale-replaces any previously parsed
ingredient list for the product; there is no incremental “add one
ingredient” tool over MCP today. Mirrors the ingredients field on the
public PATCH /products/{gtin} REST endpoint.
Output:
{raw_text, ingredients: [{name, raw_text, match_type, confidence, is_sub_ingredient}, ...]}. name is null when the parser
couldn’t resolve a mention (match_type: "UNRESOLVED").
Example: