BizNetAI
Routes natural-language shopping queries to merchant storefronts, returns normalized results.
Open source Repository Open in the app JSON README (API)
About
Routes natural-language shopping queries to merchant storefronts, returns normalized results.
Details
- Kind
- MCP servers
- Topic
- E-commerce & business
- Publisher
- biznetai
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.0.0
- Last push
- 2026-08-03T00:29:35Z
- Repository state
- ativo
- License
- MIT
- Added
- 2026-08-29 03:02:31
- Updated
- 2026-08-29 03:02:31
- Origin id
io.github.biznetai/biznetai-mcp
README
# BizNetAI MCP Server
A hosted [Model Context Protocol](https://modelcontextprotocol.io) server that routes
natural-language shopping queries to live, independent merchant storefronts and
returns normalized product and merchant results — built for AI agents and shopping
assistants that need real-time commerce data without integrating each merchant
individually.
This repository documents the **hosted service** — there is nothing to install or
run locally. Point your MCP client at the endpoint below with an API key and start
calling tools.
---
## Merchant Coverage
18,000+ live merchants and growing, across the US and Canada.
Current focus verticals:
`skincare` · `haircare` · `cosmetics` · `personal_care` · `sports_active_wear` · `clothing` · `accessories` · `fine_jewelry` · `fashion_jewelry` · `specialty_food` · `gourmet_food` · `food_and_beverage` · `home_decor` · `home_furnishings` · `candles_fragrance` · `wellness` · `luxury` · `electronics` · `consumer_goods` · `pet` · `baby_kids`
Use `list_categories` for the authoritative, up-to-date list at query time — new verticals are added periodically.
Use `find_merchants` for live merchant coverage — also updated periodically.
---
## Endpoint
| | |
|---|---|
| **URL** | `https://biznetaimcp.consumergenie.net/mcp` |
| **Transport** | `streamable-http` |
| **Auth** | Required — `Authorization: Bearer <api_key>` on every request |
The server is stateless per request — there is no session handshake to perform first.
---
## Getting an API Key
Access is self-serve:
1. Submit a request with your email, name, and a short description of your use case:
```bash
curl -X POST https://api.merchant.registration.consumergenie.net/api/developer-keys \
-H "Content-Type: application/json" \
-d '{"email": "you@example.com", "name": "Your Name", "reason": "Building an AI shopping assistant"}'
```
2. Once approved, you'll receive an email with your key (`bnai_live_...`). It's shown
once and never stored in plaintext anywhere — if you lose it, request a new one.
Each key has its own rate limit (default 60 requests/minute). Exceeding it returns
`429` with a `Retry-After` header; a missing, invalid, or revoked key returns `401`.
---
## Connecting
### MCP client (Claude Desktop, Claude Code, etc.)
Most clients speak stdio, so bridge through
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote), passing your key as a header:
```json
{
"mcpServers": {
"biznetai": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://biznetaimcp.consumergenie.net/mcp",
"--header", "Authorization:Bearer ${BIZNETAI_API_KEY}"
]
}
}
}
```
### Raw HTTP
```bash
BASE_URL="https://biznetaimcp.consumergenie.net/mcp"
API_KEY="bnai_live_..."
curl -X POST "$BASE_URL" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Authorization: Bearer $API_KEY" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_categories","arguments":{}}}'
```
---
## Tools
### `list_categories`
Return the full BizNetAI merchant category vocabulary. Useful for understanding what
kinds of merchants are available before querying.
### `find_merchants`
Find live merchants matching a query — useful when you want merchant identity before
doing a custom product lookup.
```
query str required Natural language search query
country str required ISO country code (e.g. US, CA)
limit int 0 Max merchants to return (0 = all live matches)
```
### `list_product_varieties`
List the product varieties available for a country, with how many results each has.
`find_products` always resolves your query to one of these, so this is useful for
discovering what specific product searches are likely to succeed — and how many
results to expect — before calling it.
```
country str required ISO country code (e.g. US, CA)
```
Returns a list of variety objects:
```json
{
"variety": "wireless headphones",
"product_count": 50
}
```
Varieties are country-specific — the same product type can exist under a
differently-worded variety, or not at all, in a different country.
### `find_products`
Search for products by matching your query to one of BizNetAI's curated product
varieties (e.g. `"wireless headphones"`, `"vitamin c serum"`) and returning that
variety's already-ranked top results. Call `list_product_varieties` first if you
want to see upfront what's available for a country before searching.
```
query str required Natural language product search query
country str required ISO country code (e.g. US, CA)
limit int 0 Page size (0 = server default)
offset int 0 Results to skip, for paging beyond the first page
```
Results are capped by how many products the matched variety has (usually around 50,
sometimes fewer for a niche search) — `offset`/`limit` beyond that returns whatever's
left, not an error. A query that doesn't match any known variety returns `[]`.
Returns a list of normalized product objects:
```json
{
"title": "Vitamin C Brightening Serum",
"description": "...",
"price_min": 24.60,
"price_max": 24.60,
"currency": "USD",
"available": true,
"url": "https://merchant.com/products/vitamin-c-serum",
"image_url": "https://cdn.shopify.com/...",
"store_domain": "merchant.com",
"mcp_endpoint": "https://merchant.com/api/mcp",
"merchant_position": 0,
"relevance_score": 0.79
}
```
`available` reflects whether at least one product variant was in stock as of the last
catalog refresh (boolean only — exact stock counts aren't available from all merchant
backends). `relevance_score` is a similarity score (higher is more relevant) — there's
no cutoff applied, so you can use it yourself to judge what's a good enough match for
your use case.
---
## Rate Limits & Errors
| Status | Meaning |
|---|---|
| `401` | Missing, malformed, invalid, or revoked API key |
| `429` | Rate limit exceeded — see `Retry-After` header for when to retry |
---
## Support
Questions or issues with the API — email the address you used to request your key,
or open an issue on this repository.
## License
[MIT](./LICENSE)