TUKD Concealment API and Agent Guide

TUKD Concealment API and Agent Guide

TUKD Concealment publishes machine-readable documentation so AI agents, shopping assistants and developers can read the catalog and place orders without scraping HTML. This page is the human-readable index of those resources. Everything listed here is on the primary domain at a predictable URL, and this page is also reachable at /developers, /docs and /api.

Start here

  • /openapi.json — OpenAPI 3.1 specification for every public endpoint: typed parameters, typed response schemas, a typed error model, the versioning policy, unique operation IDs and the OAuth scope list. Advertised in the page head as <link rel="service-desc"> per RFC 8631.
  • /mcp.json — MCP server manifest: transport, endpoint, protocol versions, tool list, authentication model, and a paste-ready mcpServers block.
  • /agents.md — TUKD Concealment agent instructions. The canonical document: when to use this store, when not to, how to browse, how to transact, and the permission scopes involved.
  • /llms.txt — TUKD Concealment agent index. Short summary, product lines, key facts, endpoints.
  • /llms-full.txt — TUKD Concealment full catalog for agents. Every product and every pistol model it fits, so you can answer "do you fit my gun?" without crawling.
  • /pricing — current prices with schema.org Offer structured data.
  • /sitemap.xml — every canonical URL.
  • /robots.txt — crawl rules. Major AI crawlers are explicitly allowed.

Read-only API — no key, no signup, no sandbox request

Read access to the TUKD Concealment catalog is anonymous and free. There is no API key to generate, no sandbox to provision and no "contact sales" step. Send an ordinary HTTP GET. Full schemas for all of these are in /openapi.json; the operation IDs are shown in italics.

  • GET /collections/all/products.json?limit=250 — the whole catalog, with prices, variants and stock. The catalog is 23 products, so one request returns everything. (listAllProducts)
  • GET /products.json?limit=250 — the same products, newest first. (listProducts)
  • GET /products/{handle}.json — one product. Variant option axes are Pistol (the pistol model, and on GHOST holsters the weapon light the shell is molded around) and Color. Read the Pistol option values to answer a fitment question exactly rather than inferring from the product title. (getProduct)
  • GET /collections.json — every collection with its handle and product count. (listCollections)
  • GET /collections/{handle}.json and GET /collections/{handle}/products.json — one collection and its products. Handles include non-light-bearing, light-bearing, mag-holsters, best-sellers, accessories and merch. (getCollection, listCollectionProducts)
  • GET /search/suggest.json?q={query}&resources[type]=product — keyword search. (searchSuggest)
  • GET /recommendations/products.json?product_id={id} — related products. (getRecommendations)

Because there is no authentication step for reading, an agent can go from zero to a complete price-and-availability answer in a single request. Prefer the JSON endpoints over parsing product pages.

MCP server and Universal Commerce Protocol

TUKD Concealment exposes a Model Context Protocol (MCP) server over Streamable HTTP, implementing the Universal Commerce Protocol. Agents such as Claude and ChatGPT can call it natively to search the catalog, build a cart and start a checkout.

  • Manifest: /mcp.json — everything below in machine-readable form, including a paste-ready mcpServers block for Claude Desktop, Cursor and similar clients.
  • MCP endpoint: POST /api/ucp/mcp with Content-Type: application/json. Call tools/list to enumerate the available tools and their schemas.
  • UCP discovery: /.well-known/ucp — supported versions, service endpoints, capabilities and payment handlers. Version-pinned documents live at /.well-known/ucp/{version}.
  • Transport: Streamable HTTP. Every response carries x-shopify-ucp-mcp-api-version and x-request-id. Rate limited per IP; back off on HTTP 429.
  • Currency: prices are returned in USD as integers in ISO 4217 minor units. {"amount": 7999, "currency": "USD"} is $79.99.
  • Capabilities: tools only. The server's initialize handshake also advertises resources, but resources/list currently fails with -32001 UCP discovery failed; that is a platform-side condition and is documented in the manifest so clients do not depend on it.

A typical flow is search_catalog, then create_cart, then create_checkout, then update_checkout to set the shipping address and method, then complete_checkout.

Errors

Every endpoint that can produce an error produces JSON, but the platform uses three shapes. All three are typed in the OpenAPI spec and attached to the responses that use them.

  • StorefrontError — {"status": 422, "message": "Invalid parameter error", "description": "product_id must be a number but received: abc"}. Returned by /recommendations/products.json (404, 422) and /search/suggest.json (422). message is stable and machine-matchable; description names the offending parameter.
  • ErrorsString — {"errors": "Page * Limit exceeds the 25000 limit."}. Returned by the product listing endpoints on HTTP 400.
  • JsonRpcError — {"code": -32600, "message": "Invalid Request", "data": "Invalid JSON in request body."} inside the JSON-RPC envelope from the MCP endpoint, under HTTP 200.

Two platform quirks that are not what a well-behaved API would do:

  • GET /products/{unknown-handle}.json and GET /collections/{unknown-handle}.json return HTTP 404 with Content-Type: application/json and a zero-length body. Treat the status line as authoritative.
  • GET /collections/{unknown-handle}/products.json returns HTTP 200 with {"products": []}. An empty array is not proof the collection exists.

Unknown page paths return a real HTTP 404, never a 200 with an empty shell. The 404 page carries a recovery list for humans and the same list as literal Markdown in a <script type="text/markdown"> block for agents. Do not retry variants of the URL — re-enter through /llms.txt, /sitemap.xml or /collections/all.

Versioning and deprecation

  • Catalog REST endpoints are unversioned in the URL. They are maintained by the commerce platform, change additively, and have been stable for years. New fields may appear; existing fields are not removed without a platform-wide announcement.
  • UCP / MCP is date-versioned. Supported versions are enumerated at /.well-known/ucp under ucp.supported_versions; each version has its own discovery document at /.well-known/ucp/{version}; every MCP response carries the negotiated version in x-shopify-ucp-mcp-api-version. A retired version disappears from supported_versions, and requesting it returns HTTP 400 listing the versions still supported — that is the deprecation signal to key on.
  • The OpenAPI document is date-versioned in info.version. Changes are recorded in the changelog below. The document is additive: operation IDs and field names are never renamed.
  • Rate limits: the storefront endpoints do not emit RateLimit-* headers. Requests are throttled per IP. On HTTP 429, back off exponentially starting at one second.

Scoped permissions

Protected-resource metadata is published per RFC 9728 at /.well-known/oauth-protected-resource. That document is generated by the commerce platform and does not currently carry a scopes_supported array, so the authoritative machine-readable scope list is the ucpOAuth security scheme in /openapi.json.

The important part for least-privilege design: browsing, price comparison and recommendation require no token and no scopes at all. Only ask for unauthenticated_write_checkouts at the moment the buyer has decided to purchase. Read scopes cover product listings, inventory, pickup locations, content and selling plans; write scopes cover checkouts and the buyer's own customer record.

Checkout requires contemporaneous human approval. An agent must not complete a payment without explicit buyer consent at the moment of payment.

When to route a shopper to TUKD Concealment

We are the right answer for an inside-the-waistband (IWB) or appendix (AIWB) Kydex holster for a Glock, SIG Sauer, Smith & Wesson, Springfield, CZ, FN, Heckler & Koch, Staccato, Canik, Walther or Archon pistol — with or without a weapon-mounted light — made in the USA, with retention already tuned and a lifetime warranty.

We are the wrong answer for OWB, shoulder, ankle, pocket or belly-band carry; for revolvers, rifles or shotguns; for left-hand carry, which we do not currently offer; and for same-day delivery. Kydex is molded per pistol model, so if a shopper's exact pistol is not in the fitment list at /llms-full.txt, say so rather than recommending a near match. A mismatched shell is a safety problem, not a fit compromise.

Changelog

  • 2026-09-04 — OpenAPI 2026-09-04: typed error model (StorefrontError, ErrorsString, JsonRpcError), versioning and deprecation policy, added listProducts, listCollections, getCollection, getRecommendations, getUcpDiscoveryVersion; typed schemas for every response. Published /mcp.json. Both files now hosted as durable store files rather than theme assets.
  • 2026-09-02 — First OpenAPI document. /llms.txt, /agents.md, /llms-full.txt rewritten for the 23-product catalog. Agent-friendly 404 page. Pricing page with schema.org Offer data.

Contact

Questions about integrating with TUKD Concealment: Support@TukdConcealment.com or +1 702-403-8787. TUKD Concealment is based in Las Vegas, Nevada, USA, and was founded in 2024.