# Searchspring MCP > Searchspring connects your AI agent to a full e-commerce product catalog API (Athos Commerce). It lets you converse with thousands of SKUs—querying stock levels, filtering by size/color, checking pricing, and auditing metadata—all without leaving the chat window. Use it for customer support lookups or deep inventory checks. ## Overview - **Category:** marketing-automation - **Price:** Free - **Tags:** site-search, merchandising, product-catalog, autocomplete, ecommerce, inventory-management, metadata-auditing, faceted-search ## Description This server connects your AI agent directly to a full e-commerce product catalog (Athos Commerce). You can talk to thousands of SKUs—querying stock levels, filtering by size or color, checking prices, and auditing metadata—all from the chat window. You use this for everything from customer support lookups to deep inventory checks. *** **General Catalog Queries** To start a broad search across the entire catalog using natural language keywords, you run the `search_products` tool. This function lets your agent perform a general query against all available product data, giving you an immediate list of potential matches based on what's typed. Before running a full search, you can check real-time customer behavior by calling `suggest_queries`. This pulls the exact autocomplete suggestions that shoppers are currently typing into the front end, letting your agent know exactly what terms customers are using right now. **Targeted Product Discovery** If you know the product's origin, use the `search_brand` tool. It lists every single item available from one specific manufacturer or brand name, so you don't have to sift through irrelevant results. You can find all products within a defined hierarchy by running `search_category`. For example, if you want everything under 'Mens > Shoes,' this function pulls that entire group of items into the agent’s response. When standard categories aren't enough, you execute complex search requests using specific key-value pairs via `search_custom`. This tool lets your agent run deep catalog queries by targeting parameters not covered by other functions. **Refining Search Results** You don't want 500 results when you only need five. To narrow down the list based on multiple criteria, use `search_filtered`. You format this like 'key:value,key2:value2,' letting your agent filter results by things like size *and* color simultaneously. If you only care about the cost, you limit product searches to a specific monetary window using `search_price_range`. This tool requires you to specify both a minimum and maximum dollar amount for the desired items. To make sure you see the most relevant inventory, you can reorder any set of results based on criteria like price or date by calling `search_sorted`. You just tell it what key to sort by and which direction ('asc' or 'desc') you need. If the initial list is massive—like 10,000 SKUs—you fetch a specific chunk of results using `search_pagination`, keeping your agent’s response manageable. **Deep Item Verification** If you know the exact Stock Keeping Unit number, use `search_sku`. This tool is critical because it pulls *all* specifications, current pricing details, and live stock status for one single product. It gives you total verification that the product metadata is synced up and accurate before a customer asks about it. *** Basically, your agent handles everything from keyword searches with `search_products` to confirming the exact inventory count using `search_sku`. You're running deep e-commerce logic right inside the chat. You don't have to leave the window or manually browse a storefront; you just tell your AI client what product data you need, and it gets it. ## Tools ### search_brand Lists all products available from one specific brand name. ### search_category Finds and lists all products that belong to a specified category path, like 'Mens>Shoes'. ### search_custom Runs a product search using custom key-value parameters for deep catalog querying. ### search_filtered Searches and narrows down results using multiple, defined filters (e.g., 'red:true,size:L'). ### search_pagination Retrieves a specific subset of search results when the initial list is too long. ### search_price_range Limits product searches to items priced between two specified minimum and maximum amounts. ### search_products Performs a general search across the entire catalog using a broad keyword query. ### search_sku Retrieves all product details, specs, and stock status for one specific SKU number. ### search_sorted Reorders a set of search results based on criteria like price or date ('key:direction'). ### suggest_queries Pulls the exact, current autocomplete suggestions that customers are typing into the front end. ## Prompt Examples **Prompt:** ``` Search our catalog for 'wireless headphones' and sort the results by price in ascending order. ``` **Response:** ``` I've fetched the products sorted by price in ascending order. 1. Basic Wireless Buds - $19.99 (In Stock). 2. Studio Sync Headphones - $34.50 (Low Stock). 3. Noise-Canceling Overhead - $49.00. Would you like the thumbnail images attached? ``` **Prompt:** ``` Fetch the product specs and current availability for SKU 'LPTOM-415'. ``` **Response:** ``` I queried the catalog for SKU LPTOM-415. This correlates to the 'Dell XPS 13 Ultrabook'. Pricing is set at $1,199. It features an i7 processor, 16GB RAM, and 512GB SSD. Current inventory status registers as OUT OF STOCK in our primary warehouse. ``` **Prompt:** ``` Find all products by the brand 'Nike' that cost between $50 and $100. ``` **Response:** ``` I've pulled the data using `search_brand` combined with `search_price_range`. I found 12 results for Nike between $50 and $100. The top results are: 1. Revolution 6 Running Shoes ($65.00), 2. Sportswear Club Fleece Hoodie ($55.00), and 3. Dri-FIT Training Pants ($70.00). ``` ## Capabilities ### Find products by brand The agent returns a list of items matching a specific manufacturer or brand name. ### List products in a category The agent searches and pulls all available products within a defined product hierarchy, like 'Mens > Shoes'. ### Run custom parameter searches You can execute complex search requests using specific key-value parameters not covered by standard tools. ### Perform advanced filtered searches The agent filters results based on multiple criteria, formatted as 'key:value,key2:value2'. ### Paginate search results You can fetch a specific page of results when the initial result set is too large. ### Search by price range The agent limits the product list to items that fall between two specified dollar amounts. ### General catalog search You initiate a broad search across the entire Searchspring product catalog using natural language queries. ### Check specific SKU details The agent pulls all specifications, pricing, and stock status for one exact Stock Keeping Unit (SKU). ### Sort search results You can reorder a list of products based on criteria like price or relevance ('key:direction'). ### Get autocomplete suggestions The agent retrieves the current, real-time query suggestions customers are using on the front end. ## Use Cases ### The Support Agent needs a quick price check. A customer asks, 'Is the Dell XPS 13 still $1,199?' The agent uses `search_sku` with the product identifier. It retrieves the current pricing and specs in one shot, confirming the details without forcing the user to visit a separate product page. ### The Manager needs gap analysis. The manager asks, 'List every item under 'Mens Shoes' that is out of stock.' The agent runs `search_category` and then filters the results using parameters to identify all inactive SKUs. This helps pinpoint where new inventory needs to be added. ### The Developer verifies a sorting rule. A developer wants to test if products sort correctly by date uploaded. They use `search_sorted`, applying the format 'date:desc'. The agent returns the list, proving that the API respects their custom sorting logic before they push code. ### The User needs a quick product idea. A user asks, 'What are people searching for right now?' The agent calls `suggest_queries`. This gives the user real-time data on high-traffic keywords like 'wireless headphones' or 'running shoes'. ## Benefits - Inventory Auditing: Instead of running complex database queries, you ask the agent to 'show me all out-of-stock items in Category X' using a combination of `search_category` and filtering logic. You instantly identify merchandising gaps. - Developer Validation: Before deploying new front-end filters, developers use `search_custom` to verify if custom JSON facets or complex sorting rules are parsed correctly by the API, saving hours of manual testing. - Instant Support Lookups: When responding to a customer chat, you don't leave the interface. Use `search_sku` to get accurate pricing and full specs instantly for any product number. - Targeted Product Discovery: You combine tools like `search_brand` with `search_price_range`. For example, 'Nike shoes between $50 and $100' returns a precise, actionable list of items. - Real-time Search Behavior Insight: Use `suggest_queries` to see what search terms customers are actually typing right now. This gives you data on popular searches before they hit your analytics dashboard. ## How It Works The bottom line is that your AI client handles the complex API calling so you can talk to your catalog like it's a single database query. 1. You send a natural language request (e.g., 'Show me red shoes under $75'). 2. Your AI client maps that intent to the correct tool and formats the parameters (like `search_filtered` or `search_price_range`). 3. The agent calls the Searchspring API, which returns structured data containing product names, prices, stock status, and images. ## Frequently Asked Questions **Can the AI filter catalog products by specific colors or variations?** Yes. You can instruct the agent: 'Find all Men's Shirts and filter by color: Blue and size: Medium'. The agent will natively invoke `search_filtered` passing the specific parameter facets to narrow down exactly what is requested. **Can I check autocomplete queries directly from the chat prompt?** Absolutely. Use the prompt: 'What queries do you suggest when someone types "runn"?'. The agent fires `suggest_queries` simulating a shopper and returns search trends such as 'running shoes', 'running shorts', demonstrating what customers see. **How do I ensure the integration only searches within a specific category?** You can explicitly ask the AI to restrict the search. For example: 'Using the Searchspring API, list the top 5 products strictly in the Electronics > Audio category'. The agent invokes `search_category`, returning items isolated within that structural path. **What Site ID is required before using the `search_products` tool?** You must provide your unique Searchspring Site ID during initial connection. This credential authenticates your agent and allows it to access your specific catalog data, ensuring secure operation. **If I need more than one page of results from `search_products`, should I use the `search_pagination` tool?** Yes, you must utilize `search_pagination`. This mechanism lets your agent fetch specific result pages. You specify a starting index and the number of items to retrieve for continuous data gathering. **What kind of data does the `search_sku` tool return besides just the name and price?** The `search_sku` tool returns comprehensive product details. This includes pricing, high-resolution image URLs, full technical specifications, and critical current inventory status for that exact item. **If I use the `search_filtered` tool and get no results, what should I check first?** First, verify your parameters. The format must be 'key:value,key2:value2'. Double-check that the keys you pass match the exact JSON facets available in your Searchspring catalog. **Can the `search_custom` tool help me audit product metadata or deep category trees?** Yes, you can use `search_custom`. It allows querying specific, non-standard attributes. This is useful for verifying if custom JSON facets or complex metadata are synced correctly across your entire catalog.