Skip to main content
Docs · MCP

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.

Global searchEvery Nile merchant
API keyBearer token per request
Read-onlyNo carts, no checkout
StatelessStreamable HTTP

Quickstart

From zero to a cross-merchant product search in a minute.

  1. Get a keyAsk Nile for a Nile MCP key (see Authentication) and store it as NILE_MCP_KEY.
  2. Add the server to your clientPoint any MCP client that supports remote (HTTP) servers at https://nile.app/mcp. See Connect a client.
  3. Ask a shopping questionTry “Find running shoes under $120 — no leather.” The agent calls search_global_catalog once 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_…" }
    }
  }
}

Endpoints & transport

Standard MCP over Streamable HTTP, run statelessly.

EndpointURLUse it for
Globalhttps://nile.app/mcpSearching products across every Nile merchant. Start here.
Storehttps://nile.app/mcp/{storeKey}Going deeper on one merchant: details, availability, promotions. {storeKey} is the merchant's key, e.g. example-store.
TransportStreamable HTTP, JSON responses (no SSE stream)
MethodsPOST for JSON-RPC
SessionsNone. No Mcp-Session-Id; each request stands alone.
BatchingNot supported — send one JSON-RPC message per request.
AuthAuthorization: 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 here

Search 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.

ArgumentTypeDescription
query requiredstring, ≤500The core product as a short phrase, e.g. "running shoes". One product intent per call.
alternatives optionalstring[]Synonyms for the same item, e.g. ["sneakers","trainers"]. Use instead of separate searches.
must_not optionalstring[]Terms to exclude, e.g. ["leather"].
min_price optionalnumber ≥ 0Minimum price. Put price bounds here, not in query.
max_price optionalnumber ≥ 0Maximum price.
product_type optionalstringPreferred category, e.g. "Shoes".
vendor optionalstringPreferred brand.
limit optionalinteger 1–50Max 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_countHow 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_countLength of products
query_understandingOn no_match only: the conditions that were applied, so the agent can relax one and retry
next_cursorReserved; always null today

Search well

  • One call per product. Pack synonyms into alternatives, exclusions into must_not and prices into min_price/max_price rather than searching several times.
  • On no_match, read query_understanding, drop the least important condition (usually a price bound) and retry once.
  • Keep product_url exactly 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.

ToolWhat it returns
catalog_searchProducts in this store matching query (2–200 chars): title, handle, url, vendor, type, price range, image.
product_detailDescription, up to 3 images, price range and configured options (size, color…).
get_inventoryin_stock / out_of_stock plus per-variant available and price. Point-in-time; never quantities or SKUs.
get_promotionsCompare-at discounts and promotion tags on the product. Never private discount codes.
get_brand_infoTakes brand or vendor. A sample of that brand's products and main product types in this store.
get_trend_signalNew-arrival, merchandising-tag and assortment-depth signals. Not sales or popularity data.
clarify_user_intentTakes 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.

HTTPJSON-RPC codeWhen
400-32700Body is not valid JSON
400-32600Invalid 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-32000Request timed out
413-32600Body too large
200tool isErrorBad arguments, product not found, or search temporarily unavailable — safe to retry later

Limits

  • Global search: up to 50 results per call; query up to 500 characters.
  • Store tools: 64 KB request body, 15-second timeout.
  • Pagination: not yet supported; raise limit instead.

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_url to 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 2026Global 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