The short answer
MCP suits tool use inside an agent workflow, where a model decides mid-conversation that a product search is warranted. REST suits direct application and service integration, where your own code already knows when to search. The useful product is the structured product data behind both. With simlir, authentication, credits, market scope, response shape and limits are identical either way — so this is an integration decision, not a data-model decision, and it is reversible.
What MCP does
The Model Context Protocol is an open standard for exposing capabilities to a model as discoverable tools. Instead of you writing an adapter that describes an API to a model and parses what it produces, a compatible client connects to an endpoint, calls tools/list, and learns what is available — names, parameters, types and descriptions — at runtime.
For simlir, connecting is a configuration entry:
{
"mcpServers": {
"simlir": {
"url": "https://simlir.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}Once connected, a compatible client discovers three tools automatically:
| Tool | Cost | What it does |
|---|---|---|
simlir_search_products | 2 credits | Semantic search across the product database. Takes query and a required market, plus optional category, brand, min_price, max_price, limit. |
simlir_search_products_by_image | 3 credits | Visual search from a hosted HTTPS image_url, returning the same product shape plus a visual_similarity_score. |
simlir_lookup_products_by_identifier | 1 credit | Exact lookup by GTIN, MPN or retailer SKU. type=auto tries GTIN, then MPN, then SKU. |
What you gain is decision-making at the right layer. The model sees a shopper ask about a product, recognises that it needs evidence, calls the tool, and continues the conversation with structured results in hand. You did not have to predict that moment in advance.
What you give up is control over timing. The model decides when to call, which means it also decides when to spend credits. That is manageable — but it is a real difference.
What REST does
REST is the canonical contract surface. Four endpoints, standard HTTP, callable from any server or runtime, with a documented OpenAPI reference.
| Endpoint | Cost | Use it for |
|---|---|---|
GET /v1/search | 2 credits | The primary endpoint. Natural language query, semantically ranked products. Requires q and gl. |
GET /v1/lookup | 1 credit | Exact match by GTIN, MPN or retailer SKU. Best for merchant-feed joins, catalogue sync and ERP workflows. |
POST /v1/search/image | 3 credits | Search from a hosted HTTPS product photo or screenshot. |
GET /v1/product | 1 credit | Follow-up lookup by the stable simlir UUID returned in every search result. |
curl "https://simlir.com/api/v1/search?q=protein+powder&gl=gb&limit=5" \
-H "Authorization: Bearer sk_your_key"The fourth endpoint is the one teams overlook and then wish they had used from the start. Every search result carries a stable id that never changes. Cache it, and a later fetch of that exact product costs 1 credit instead of re-running a 2-credit search:
curl "https://simlir.com/api/v1/product?id=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
-H "Authorization: Bearer sk_your_key"For a browsing interface where users click into results, revisit saved comparisons, or refresh a watchlist, that single pattern is usually the largest available saving.
curl "https://simlir.com/api/v1/lookup?identifier=8806095048789&type=gtin&gl=gb&retailer=Currys&limit=10" \
-H "Authorization: Bearer sk_your_key"Decision table by use case
| What you are building | Route | Why |
|---|---|---|
| Conversational shopping assistant | MCP | The model decides when product evidence is needed. No adapter to maintain. |
| Coding or research agent that occasionally needs product data | MCP | Occasional, unpredictable use is exactly what tool discovery is for. |
| Product comparison web page | REST | Your code knows when to search. You want caching and predictable spend. |
| Price monitoring job | REST | Scheduled, identifier-driven, no conversation involved. Use /v1/lookup or /v1/product. |
| Merchant-feed enrichment | REST | You already hold GTINs. Exact lookup at 1 credit, no semantic ranking needed. |
| Visual search in a mobile app | REST | Your client controls image hosting and the request lifecycle. |
| Assistant with its own web interface | Both | MCP in the conversation, REST for pages, refreshes and background jobs. |
| Internal analytics or market intelligence | REST | Batch, scheduled, joined against your own data. |
Authentication and application boundaries
Authentication is identical on both routes: a Bearer token in the Authorization header. Keys are created in the dashboard and are hashed on our side, so they cannot be recovered — store them securely and create separate keys per application so you can revoke one without disturbing the others. Version 1 does not expose selectable scopes or a sandbox environment.
Rate limits also apply to both routes identically: a free account gets 10 requests per minute with a burst of 20 and a daily cap of 10; standard allows 1,000 per minute with a burst of 5,000 and no daily cap. These are request ceilings, not a data allowance — paid operations still consume credits. Every response carries X-RateLimit-Remaining and X-RateLimit-Reset.
Response consistency across both routes
This is the part that makes the decision low-risk: MCP and REST return the same product shape. The same identifiers, the same spec object, the same price snapshot with its as_of date, the same links, the same market echo.
Three behaviours are worth knowing because they hold on both routes:
limitis a ceiling, not a promise. A post-search sanity filter can return fewer items or zero when the candidate page is clearly the wrong product type. Readmeta.count.- Market is required and never inferred.
glon REST search and lookup,marketon image search and the MCP tools. The response echoes it; a mismatch is an integration bug. - Scores are not interchangeable.
relevance_scoreappears only on semantic search results (cosine similarity, 0–1).visual_similarity_scoreappears only on image results. Do not compare or blend them.
On lookup specifically, the response tells you how the match was made: requested_type echoes what you asked for, while resolved_type and matched_field tell you which field actually matched. Note that when you send type=mpn, the product field in the response is still model_number.
When to use both
Most production shopping assistants end up on both routes, and that is a healthy outcome rather than a sign of indecision. A typical division:
- MCP inside the conversation. The model calls the search tool when the shopper asks something that needs product evidence.
- REST around it. Your backend re-fetches cached product UUIDs to refresh a saved comparison, joins identifiers from a partner feed, runs a nightly price check, and serves the product detail pages.
Because both routes draw on the same credit balance and return the same shape, you can move work between them as your cost profile changes without touching your data layer.
Implementation checklist
- Decide who initiates the searchModel-initiated points to MCP; code-initiated points to REST.
- Create a separate API key per applicationKeys are hashed and unrecoverable, so revocation should be surgical.
- Never ship a shared key in a distributed client configKeep it server-side and expose your own interface instead.
- Send the market explicitly on every callgl or market, and compare it against the echoed value.
- Cache product UUIDs/v1/product at 1 credit beats repeating a 2-credit search.
- Use exact lookup when you already hold an identifier1 credit, no ranking ambiguity.
- Read meta.count, not the array length you requestedShort and empty pages are legitimate responses.
- Handle 402, 429, 502 and 503 distinctlyOut of credits, rate limited, embedding failure, service unavailable.
- Back off using X-RateLimit-ResetRather than a fixed retry interval.
- Log credits used per featureSo you can see which surface is driving spend before the invoice does.
Frequently asked questions
Is MCP slower than REST?
Do MCP tool calls cost more credits than REST calls?
Can I switch from one to the other later?
Which MCP clients work with simlir?
tools/list. The MCP setup guide has the current details.