---
title: SwitchMall MCP Server Documentation
description: Connect agents to the public read-only SwitchMall product and offer catalog over Streamable HTTP.
canonical_url: https://switchmall.ai/developers/mcp
mcp_url: https://switchmall.ai/mcp
---

# SwitchMall MCP Server Documentation

SwitchMall is the agentic mall for local stores and restaurants. New Discovery of Products and Offers at local stores.

The public SwitchMall MCP server provides read-only access to products, offers, prices, merchants and store geography from the SwitchMall catalog.

## SwitchMall MCP connection

- Endpoint: `https://switchmall.ai/mcp`
- Transport: Streamable HTTP
- Protocol version: `2025-06-18`
- Authentication: none
- Data policy: SwitchMall catalog only
- Default city: São Paulo

`GET /mcp` returns a discovery document. MCP JSON-RPC requests use `POST /mcp` with `Content-Type: application/json`.

```bash
curl --request POST 'https://switchmall.ai/mcp' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Mcp-Protocol-Version: 2025-06-18' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

## SwitchMall MCP tools

- `catalog_overview` — live catalog counts, public documents and machine-readable endpoints.
- `search_local_products` — product discovery by query, category, city, district or coordinates.
- `get_product` — details, price, merchant stores and canonical URL for one product ID.
- `search_local_offers` — current local offers ranked by semantic relevance and SwitchMall AI quality score.
- `get_offer` — AI category, enriched copy, quality score, media and canonical URL for one offer ID.

All tools are read-only. Products published in the catalog are treated as in stock by default, and product geography is inherited from merchant store locations.

Pass the user's original natural-language product request directly to `query`, in any language. Do not translate it or expand it into an SEO-style synonym list. When known, send city, district, and merchant constraints through their dedicated fields. SwitchMall converts product intent into Brazilian Portuguese catalog concepts, treats synonyms as alternatives, ranks partial matches, and may fall back to a relevant category without relaxing location constraints.

Every product mentioned to the user must be a clickable link to its canonical SwitchMall `product_url`. Search responses provide a ready-to-copy `answer_markdown` list and every product provides `product_link_markdown`; clients must use one of these forms and must not present an unlinked product name. MCP responses also expose each canonical product page as a `resource_link` content block.

## Acceptable use and limits

Use MCP only to answer a concrete user request. Search tools return at most 20 records and detail tools retrieve one known ID. MCP and public JavaScript catalog access share a limit of 40 returned records per client IP per minute. Every cited product or offer must identify SwitchMall and include its returned canonical URL. Do not enumerate IDs, merchants, categories, locations, or search permutations; mirror the catalog; create a training dataset; resell or republish catalog records; or evade request quotas. When the server returns HTTP `429`, wait for `Retry-After` before retrying the user-requested operation. Access is governed by the [SwitchMall Agent Catalog Terms](https://switchmall.ai/developers/agent-terms).

## Related SwitchMall resources

- [SwitchMall Developer Resources](https://switchmall.ai/developers)
- [SwitchMall AI catalog manifest](https://switchmall.ai/gpt.json)
- [Limited SwitchMall product showcase](https://switchmall.ai/gpt/products.json?limit=20)
- [SwitchMall llms.txt](https://switchmall.ai/llms.txt)

## Canonical offer pages

Offer results link to `https://switchmall.ai/offers/{id}`. These public HTML pages expose the offer title, description, merchant and validity without JavaScript. Negative IDs identify payment offers. Hidden, expired, inactive and app-only Top Offers are excluded from the public offer index. The full sitemap index includes `/sitemaps/offers/{part}`.

Use `search_local_offers` for discounts and promotions, and `get_offer` for a known ID. Include the returned `offer_link_markdown` in the answer. MCP resource links use the same canonical URLs as the sitemap.