For Humans

Shopping MCP guide

Use this guide to connect an agent, understand the tool contract, and inspect the product facts and response shapes it receives. Amazon.com is the currently supported product source.

Version 0.1.0Updated July 11, 2026

Quick start

Connect using Streamable HTTP. No consumer API key is required for the current public MVP.

Agent instruction

Connect to this Streamable HTTP MCP server:
https://menlolabs.dev/mcp

Discover the available tools, preserve the user's explicit constraints,
and include every selected product's product_url in your response.

Looking for the agent-readable version?

Send the raw Markdown URL to an agent or paste its contents into the conversation.

For Agents →

Connect your agent

The server uses Streamable HTTP at https://menlolabs.dev/mcp. Add it once in your agent client, restart or open a fresh session, then ask the client to list the available tools.

Codex CLI or app

Terminal

codex mcp add shopping-mcp --url https://menlolabs.dev/mcp

Hermes Agent

Terminal

hermes mcp add shopping-mcp --url https://menlolabs.dev/mcp

When Hermes asks whether the server requires authentication, choose no, then enable both discovered tools.

Generic MCP client

Clients that accept JSON configuration generally use this shape. Some clients name the top-level field differently.

MCP configuration

{
  "mcpServers": {
    "shopping-mcp": {
      "url": "https://menlolabs.dev/mcp"
    }
  }
}

After connecting, verify that search_products and build_product_kit appear. If they do not, test the endpoint, confirm Streamable HTTP support, and restart the client.

Tool selection

Situation	Tool	Guidance
Specific product discovery	`search_products`	Use for a concrete query with optional price, rating, sponsorship, and sort constraints.
Broad shopping need	`build_product_kit`	Use when the user describes a goal and needs categories plus products. Expect partial results when provider limits apply.

Tool reference

`search_products`

Required: query. Optional: max_results (1–10), sort, min_price, max_price, min_rating, exclude_sponsored, and amazon_domain. Only amazon.com is supported.

Supported sort values: best_match, featured, best_rated, bestselling, newest, price_low_to_high, and price_high_to_low.

Example call

{
  "query": "wireless mechanical keyboard",
  "max_results": 5,
  "sort": "best_rated",
  "max_price": 120,
  "min_rating": 4.2,
  "exclude_sponsored": true
}

`build_product_kit`

Required: theme. Optional: budget, max_categories (maximum 3), products_per_category (maximum 5), and sort. The service uses at most two uncached provider searches per kit.

Example call

{
  "theme": "I'm returning to recreational running",
  "budget": 250,
  "max_categories": 3,
  "products_per_category": 3,
  "sort": "best_match"
}

Example response

{
  "theme": "returning to recreational running",
  "status": "success",
  "categories": [
    {
      "category": "Running shoes",
      "reason": "Core footwear for regular running.",
      "search_query": "beginner daily trainer running shoes",
      "products": [
        {
          "asin": "B0EXAMPLE",
          "name": "Example Daily Trainer",
          "product_url": "https://www.amazon.com/dp/B0EXAMPLE",
          "price": { "amount": 89.99, "currency": "USD" },
          "rating": 4.6,
          "review_count": 2840
        }
      ]
    }
  ]
}

Operating rules

Preserve every explicit user constraint. Do not silently relax price, brand, audience, style, rating, or sort requirements.
Retrieve multiple candidates before making a recommendation unless the user explicitly requests one result.
Consider rating and review count together; neither is sufficient on its own.
Never invent a price, rating, review count, ASIN, Prime status, availability claim, image, or URL.
Treat price, shipping, availability, and Prime status as time-sensitive retrieved facts.
Clearly distinguish retrieved product facts from your interpretation or recommendation.
Always show the returned product_url for each product you present.
Do not expose API keys, internal provider parameters, or backend implementation details.

Response semantics

Product facts come from the product-data provider or its cached normalized results. product_url is the source Amazon URL; tracked_url is an optional Menlo redirect used for click measurement. Fields may be null when the source does not expose them.

search_products response

{
  "request_id": "01f...",
  "status": "success",
  "canonical_query": "wireless mechanical keyboard",
  "cache_status": "hit",
  "products": [
    {
      "asin": "B0EXAMPLE",
      "name": "Example Mechanical Keyboard",
      "product_url": "https://www.amazon.com/dp/B0EXAMPLE",
      "tracked_url": "https://menlolabs.dev/r/a8K2mP",
      "image_url": "https://...",
      "price": { "amount": 89.99, "currency": "USD", "display": "$89.99" },
      "rating": 4.6,
      "review_count": 2840,
      "is_prime": true,
      "price_checked_at": "2026-07-11T18:00:00Z"
    }
  ]
}

cache_status is hit or miss. Theme requests can return partial when a cache-miss or global provider limit prevents every category from being fetched.

Limitations

Results currently focus on Amazon.com product search data.
Prices and availability can change after retrieval.
Shipping, Prime, and variation-level metadata may be unavailable or incomplete.
The MCP does not complete checkout or purchase products.
Searches are anonymous, cache-first, and rate-limited. A client may make 10 searches per UTC day.
Tracked product links record clicks. Affiliate attribution is not currently configured.

For the raw Markdown version, read or send /agents.md. For machine-readable discovery, read /llms.txt.