Introduction
gaisho is a shopping API and MCP server for agents and applications researching US retail products. It turns a shopper’s needs into product choices, checks quoted prices and sellers, and compares purchase options. Use its tools individually or combine them into a shopping assistant that explains its recommendations and links to the relevant listings.
Two ways to connect
The same eight shopping tools are available through MCP and REST. Choose MCP when you want an agent to select and call tools during a conversation. Choose REST when your application controls the requests and handles the responses.
- [MCP server](https://gaisho.co/docs/mcp): Give the installation prompt to your personal agent, such as Claude or Codex. Follow its guidance to connect, sign in and start asking shopping questions.
- [REST API](https://gaisho.co/docs/api): Call the tools from your application, backend or scripts with an API key. Send JSON arguments and receive JSON responses containing readable summaries and the tool’s result fields.
For example, after connecting gaisho through MCP, ask your agent:
Ask your agent
```
Find over-ear noise-cancelling headphones under $200 with at least 30 hours of battery life. Compare the options and explain the trade-offs.
```MCP installation has the prompt to send your agent. Quickstart covers sign-in and a first search for either connection.
What you can do
Discover products
Start with a broad need, a specific model or a picture. Discovery tools help an agent understand the category and find candidates using the shopper’s stated requirements.
- [Explore a category](https://gaisho.co/docs/mcp/get_category_overview): See the specifications, options and price distributions available for a product type. Use this to explain what to compare or to help a shopper refine a broad request such as “a robot vacuum for my apartment.”
- [Search by requirements](https://gaisho.co/docs/mcp/search_products): Describe the product, required features, size, quantity and budget in natural language. Results include candidate products and interpreted conditions, helping you see which requirements were applied and which still need checking.
- [Search from a picture](https://gaisho.co/docs/mcp/search_products_by_image): Use a product photo or screenshot to find catalog matches and similar items. Results separate likely matches from other sizes, variants and substitutes. A candidate that has not been verified is not a confirmed match.
Research a purchase
Once a shopper has a candidate or a quote, inspect the product, the listing and the seller as separate parts of the decision.
- [Read product details](https://gaisho.co/docs/mcp/get_product): Retrieve specifications, ratings, reviews and available offers. Request one product or compare details for up to eight products together, then use the returned identifiers to continue the research.
- [Inspect a listing](https://gaisho.co/docs/mcp/get_offer): Check the seller, purchase URL, price and stated coupon terms for a selected offer. Keep these details together so the price you recommend belongs to the listing the shopper opens.
- [Assess a price](https://gaisho.co/docs/mcp/vet_price): Ask whether a quoted USD total is reasonable for a product or requirement. The result includes a price verdict, suggested action, confidence, summary and supporting evidence. For multipacks or measured goods, include the quantity covered by the total.
- [Check a seller](https://gaisho.co/docs/mcp/vet_seller): Assess an online store or marketplace seller using a domain, seller identifier or listing link. The result names the seller that was checked, gives a trust level with the facts behind it, and notes anything a buyer should know.
Compare and present options
- [Compare purchase options](https://gaisho.co/docs/mcp/find_deals): Look for offers for the selected product, alternatives with compatible key specifications, or models with upgrades and downgrades. Results describe differences, prices, coupon terms and comparison coverage so an agent can explain the choices.
From a question to purchase options
Which tools to use depends on what the shopper already has. A broad request needs discovery; an exact product link may be ready for a detail or price check. There is no need to run every tool for every question.
- Clarify the need. For “headphones for commuting,” explain useful category choices and ask about the shopper’s budget or required features when needed.
- Build a shortlist. Search with the stated requirements, inspect candidate details and explain meaningful differences. Keep unresolved requirements visible.
- Evaluate an option. Check the quoted total and quantity, compare purchase options, and inspect the selected listing or seller when relevant.
- Present the choice. Summarize the reasons, trade-offs and purchase links.
Product IDs connect discovery to product research. Offer IDs identify individual listings for seller, price and purchase-link checks. Reuse IDs returned by the tools rather than inventing identifiers or mixing details from different offers.
Designed for shopping decisions
Requirements stay part of the answer
A shopper can specify a budget, dimensions, pack size, required features and preferences. Search results explain the conditions used, while purchase comparisons describe differences and unverified requirements. An agent can then tell a suitable option from one that still needs checking.
Judgments come with reasons
Price and seller assessments include explanations an agent can relay to the shopper. A price label is accompanied by evidence and confidence; a seller assessment identifies who was checked and the facts supporting the result. Use these reasons to explain a recommendation.
Research connects to a listing
Product and offer identifiers let you move from a broad search to specifications, purchase comparisons and the chosen listing. Results can carry purchase URLs, seller details and coupon terms, so an application can show them next to its recommendation.
Coverage and interpreting results
gaisho focuses on US retail shopping, with prices expressed in USD. Product availability and detail coverage vary by category and retailer. A comparison describes the options found for that request; it does not establish the lowest price across every store.
Price references may include estimates, which should not be presented as live seller offers. A suspicious price calls for verification and is not proof of fraud. Seller assessments describe available evidence rather than guaranteeing an order.
Prices, stock, coupons, tax and shipping can change. Follow the selected offer’s terms and confirm the final checkout amount on the retailer’s site. gaisho does not place orders or take payment.
Next steps
- [Connect your agent](https://gaisho.co/docs/mcp): Send the installation prompt to your personal agent, complete sign-in and verify the connection.
- [Make your first request](https://gaisho.co/docs/quickstart): Follow the MCP or REST path from account setup to a product search.
- [Browse the API reference](https://gaisho.co/docs/api): Read authentication, request examples, input fields and response fields for your application.
- [Get help](https://gaisho.co/support): Contact the team about connection issues, account access or product results.