Nile MCP
Search products across every Nile merchant from any AI agent. One endpoint, one tool call, ranked results with links shoppers can buy from — over the open Model Context Protocol, secured with your Nile MCP key.
What it is
A single MCP server for product discovery across the whole Nile catalog — not tied to any one store.
Ask for “running shoes under $120, no leather” and the Nile MCP searches every participating merchant at once, understands the intent, ranks the matches and returns each product with its price, image, merchant and a link to buy. Agents like Claude, ChatGPT and Cursor can use it to answer shopping questions with real products instead of guesses.
When an agent needs to go deeper on one merchant — full product details, variant availability, promotions — it can also use that merchant's store tools.
Quickstart
From zero to a cross-merchant product search in a minute.
- Get a keyAsk Nile for a Nile MCP key (see Authentication) and store it as
NILE_MCP_KEY. - Add the server to your clientPoint any MCP client that supports remote (HTTP) servers at
https://nile.app/mcp. See Connect a client. - Ask a shopping questionTry “Find running shoes under $120 — no leather.” The agent calls
search_global_catalogonce and shows matches from several merchants.
Or call it directly
The server is plain JSON-RPC 2.0 over HTTP, so curl works.
# List the tools curl -s https://nile.app/mcp \ -H "Authorization: Bearer $NILE_MCP_KEY" \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' # Search every merchant curl -s https://nile.app/mcp \ -H "Authorization: Bearer $NILE_MCP_KEY" \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":2,"method":"tools/call", "params":{"name":"search_global_catalog", "arguments":{"query":"running shoes","alternatives":["sneakers","trainers"], "must_not":["leather"],"max_price":120,"limit":5}}}'
Connect a client
Pick your tool. Each snippet adds the Nile MCP and sends your key from NILE_MCP_KEY.
claude_desktop_config.json · uses the mcp-remote bridge to send the key
{
"mcpServers": {
"nile": {
"command": "npx",
"args": ["mcp-remote", "https://nile.app/mcp",
"--header", "Authorization:Bearer ${NILE_MCP_KEY}"],
"env": { "NILE_MCP_KEY": "nile_mcp_…" }
}
}
}
claude mcp add --transport http nile https://nile.app/mcp \
--header "Authorization: Bearer $NILE_MCP_KEY"
~/.cursor/mcp.json
{
"mcpServers": {
"nile": {
"url": "https://nile.app/mcp",
"headers": { "Authorization": "Bearer ${env:NILE_MCP_KEY}" }
}
}
}
.vscode/mcp.json · VS Code prompts for the key once and stores it securely
{
"inputs": [
{ "type": "promptString", "id": "nile-mcp-key", "description": "Nile MCP key", "password": true }
],
"servers": {
"nile": {
"type": "http",
"url": "https://nile.app/mcp",
"headers": { "Authorization": "Bearer ${input:nile-mcp-key}" }
}
}
}
npx @modelcontextprotocol/inspector # Transport: Streamable HTTP · URL: https://nile.app/mcp # Authentication → Bearer Token: your Nile MCP key
Endpoints & transport
Standard MCP over Streamable HTTP, run statelessly.
| Endpoint | URL | Use it for |
|---|---|---|
| Global | https://nile.app/mcp | Searching products across every Nile merchant. Start here. |
| Store | https://nile.app/mcp/{storeKey} | Going deeper on one merchant: details, availability, promotions. {storeKey} is the merchant's key, e.g. example-store. |
| Transport | Streamable HTTP, JSON responses (no SSE stream) |
| Methods | POST for JSON-RPC |
| Sessions | None. No Mcp-Session-Id; each request stands alone. |
| Batching | Not supported — send one JSON-RPC message per request. |
| Auth | Authorization: Bearer <key> on every request. See Authentication. |
Authentication
Every request needs a Nile MCP key, sent as a bearer token.
Authorization: Bearer nile_mcp_xxxxxxxxxxxxxxxxxxxxxxxx
Getting a key
Keys are issued by Nile. Contact support@nile.app with the name of your agent or app. Every key can use global search; access to store endpoints is granted per key, and calling a store outside the key's access returns 403.
Keeping it safe
- Treat the key like a password. Keep it on your server or in your MCP client's local config — never in browser code, a public repo or a prompt.
- Load it from an environment variable, e.g.
NILE_MCP_KEY, as in the examples on this page. - If a key leaks, ask Nile to revoke it. A new key works right away; the old one stops working as soon as it's revoked.
What happens without a valid key
A missing, malformed or revoked key returns 401 Unauthorized with a WWW-Authenticate: Bearer header, before any tool runs. See Errors.
Global search
One tool on https://nile.app/mcp. Read-only, idempotent, and returns structuredContent plus the same JSON as text.
search_global_catalogStart hereSearch active products across all participating Nile merchants. Understands the shopper's intent, ranks results, and folds near-duplicates from the same merchant into one result.
| Argument | Type | Description |
|---|---|---|
query required | string, ≤500 | The core product as a short phrase, e.g. "running shoes". One product intent per call. |
alternatives optional | string[] | Synonyms for the same item, e.g. ["sneakers","trainers"]. Use instead of separate searches. |
must_not optional | string[] | Terms to exclude, e.g. ["leather"]. |
min_price optional | number ≥ 0 | Minimum price. Put price bounds here, not in query. |
max_price optional | number ≥ 0 | Maximum price. |
product_type optional | string | Preferred category, e.g. "Shoes". |
vendor optional | string | Preferred brand. |
limit optional | integer 1–50 | Max results. Default 10. |
Returns
status | "matched", "no_match" or "degraded" (results returned with reduced ranking quality) |
products[] | product_id, title, price, currency, product_url, image_url, merchant {id, name, domain}, relation, relevance_score (0–1), similar_count |
relation | "exact" (what was asked for), "substitute" (could replace it) or "related" |
similar_count | How many more products from the same merchant also matched — e.g. other colors listed separately. Read it as “at least”. |
related[] | Adjacent products, same shape as products[] |
returned_count | Length of products |
query_understanding | On no_match only: the conditions that were applied, so the agent can relax one and retry |
next_cursor | Reserved; always null today |
Search well
- One call per product. Pack synonyms into
alternatives, exclusions intomust_notand prices intomin_price/max_pricerather than searching several times. - On
no_match, readquery_understanding, drop the least important condition (usually a price bound) and retry once. - Keep
product_urlexactly as returned. It carries Nile's attribution parameters, which is how merchants know the shopper came from your agent.
Example
Request
{
"jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": {
"name": "search_global_catalog",
"arguments": { "query": "running shoes", "alternatives": ["sneakers"], "max_price": 120, "limit": 2 }
}
}
Response · structuredContent (merchants are examples)
{
"status": "matched",
"returned_count": 2,
"products": [
{
"product_id": "5f0c2a8e-…",
"title": "Men's Lightweight Cushioned Running Shoes",
"price": 52.16, "currency": "USD",
"product_url": "https://example-store.com/products/lightweight-running-shoes?utm_source=nile_direct&…",
"image_url": "https://cdn.example-store.com/running-shoes.jpg",
"merchant": { "id": "0193e…", "name": "Example Store", "domain": "example-store.com" },
"relation": "exact", "relevance_score": 0.98, "similar_count": 2
},
{
"product_id": "a71d94c3-…",
"title": "Women's Road Running Shoes",
"price": 89.00, "currency": "USD",
"product_url": "https://acme-athletics.example/products/road-runner?utm_source=nile_direct&…",
"image_url": "https://cdn.acme-athletics.example/road-runner.jpg",
"merchant": { "id": "0198b…", "name": "Acme Athletics", "domain": "acme-athletics.example" },
"relation": "exact", "relevance_score": 0.97, "similar_count": 0
}
],
"related": [],
"query_understanding": null,
"next_cursor": null
}
Store tools
Optional, per-merchant tools on https://nile.app/mcp/{storeKey} for when an agent has picked a merchant and needs more than a search result.
Each store endpoint speaks for that merchant only. Prices are in the merchant's currency. All tools are read-only and take a product_handle (from that store's catalog_search) unless noted.
| Tool | What it returns |
|---|---|
catalog_search | Products in this store matching query (2–200 chars): title, handle, url, vendor, type, price range, image. |
product_detail | Description, up to 3 images, price range and configured options (size, color…). |
get_inventory | in_stock / out_of_stock plus per-variant available and price. Point-in-time; never quantities or SKUs. |
get_promotions | Compare-at discounts and promotion tags on the product. Never private discount codes. |
get_brand_info | Takes brand or vendor. A sample of that brand's products and main product types in this store. |
get_trend_signal | New-arrival, merchandising-tag and assortment-depth signals. Not sales or popularity data. |
clarify_user_intent | Takes the shopper's raw query. Returns the likely intent, missing details and up to 3 follow-up questions. |
Example: check availability at a store
curl -s https://nile.app/mcp/example-store \ -H "Authorization: Bearer $NILE_MCP_KEY" \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":3,"method":"tools/call", "params":{"name":"get_inventory","arguments":{"product_handle":"lightweight-running-shoes"}}}'
Errors
Transport problems come back as HTTP errors. Tool problems come back as a normal result with isError: true and a readable message.
| HTTP | JSON-RPC code | When |
|---|---|---|
400 | -32700 | Body is not valid JSON |
400 | -32600 | Invalid request, or a JSON-RPC batch (array) was sent |
401 | — | Key missing, malformed or revoked |
403 | — | Key is valid but doesn't have access to this store endpoint |
404 | — | Unknown storeKey |
408 | -32000 | Request timed out |
413 | -32600 | Body too large |
200 | tool isError | Bad arguments, product not found, or search temporarily unavailable — safe to retry later |
Limits
- Global search: up to 50 results per call;
queryup to 500 characters. - Store tools: 64 KB request body, 15-second timeout.
- Pagination: not yet supported; raise
limitinstead.
Be gentle. Retry tool errors with backoff, and don't poll. Availability is point-in-time; re-check right before you tell a shopper something is in stock.
Building a shopping agent
Rules that keep answers accurate and shoppers happy.
- Start with
search_global_catalog. Use one call per product the shopper wants. - Show the merchant's name with every product, so shoppers know where they're buying.
- Use store tools only for a merchant you already found, and only to go deeper.
- Never claim quantities, reservations or guaranteed stock. Never claim cart, checkout, order or account access.
- Send the shopper to
product_urlto buy, unchanged.
A typical flow
shopper: "Running shoes under $120, no leather — I'm a size 9" → search_global_catalog query="running shoes", alternatives=["sneakers"], must_not=["leather"], max_price=120 → pick 2–3 results from different merchants → get_inventory on https://nile.app/mcp/{storeKey}: is size 9 available? → reply with title, price, merchant and product_url
Data & privacy
- Key-protected. Only callers with a Nile-issued key can reach the server.
- Read-only. No tool writes anything, anywhere.
- Shopping fields only. Results contain what shoppers already see on merchant websites.
- Never exposed: stock quantities, warehouse data, private discount codes, customer or order data.
- Not indexed: MCP endpoints are excluded from search engines.
Changelog
| Nov 2026 | Global search: search_global_catalog on https://nile.app/mcp with alternatives, must_not, relevance and similar_count. Store tools on /mcp/{storeKey}. Access requires a Nile MCP key. |
Questions, or want a key? support@nile.app