{
  "object": "doc",
  "title": "How do I connect an AI agent to Cartroute with MCP?",
  "description": "Remote MCP server: setup for Claude Code, Cursor and other clients, tools, resources and prompts.",
  "section": "Agents and integrations",
  "url": "https://cart-route.com/docs/mcp",
  "updated": "2026-09-23",
  "prev": "https://cart-route.com/docs/pages-as-json",
  "next": "https://cart-route.com/docs/guides/claude",
  "text": "Add `https://cart-route.com/mcp` as a remote MCP server with the header `Authorization: Bearer cr_live_...`. The server speaks Streamable HTTP, exposes 7 tools, and works with Claude Code, Claude Desktop, Cursor and any client that supports remote servers. Discovery needs no key; the four data tools cost one credit per call.\n\nPOST https://cart-route.com/mcp\n\n## How do I add it to Claude Code?\n\n```\nclaude mcp add --transport http cartroute https://cart-route.com/mcp \\\n  --header \"Authorization: Bearer $CARTROUTE_API_KEY\"\n```\n\n## How do I add it to Cursor or another JSON-configured client?\n\n```\n{\n  \"mcpServers\": {\n    \"cartroute\": {\n      \"url\": \"https://cart-route.com/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer cr_live_...\"\n      }\n    }\n  }\n}\n```\n\n## What if my client only supports local (stdio) servers?\n\nBridge it with `mcp-remote`, which runs locally and forwards to the remote server:\n\n```\n{\n  \"mcpServers\": {\n    \"cartroute\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"https://cart-route.com/mcp\",\n        \"--header\",\n        \"Authorization:${CARTROUTE_AUTH}\"\n      ],\n      \"env\": {\n        \"CARTROUTE_AUTH\": \"Bearer cr_live_...\"\n      }\n    }\n  }\n}\n```\n\n## Which tools does the server expose?\n\n| Tool | What it does |\n\n| `search_products` | Search 12 US retailers (Amazon, Walmart, Best Buy, Costco, Target, Newegg, B&H, Home Depot, Lowe's, Sam's Club, Staples, Micro Center) in one call. Returns matched products, each with every retailer offer, landed price (price + shipping), the best applicable coupon, effective price after that coupon, and a 90-day price verdict. Natural-language price bounds in the query ("under $400") are understood. Costs 1 credit. |\n| `get_product` | Full product record: specs, every retailer offer, applicable coupons and price verdict. Accepts a product id (prd_...), slug, GTIN or MPN. Costs 1 credit. |\n| `get_price_history` | Daily lowest price and per-retailer series for one product. Use it to judge whether today's price is a real deal. Costs 1 credit. |\n| `find_coupons` | Active coupon codes and automatic promotions, with redemption success rate and sample size. Filter by retailer, category or product. Costs 1 credit. |\n| `list_retailers` | Retailer ids, membership requirements, free-shipping thresholds, return windows and refresh intervals. Free. |\n| `list_categories` | Category names with product counts, for use as the `category` filter. Free. |\n| `get_account` | Remaining credits and whether the email-verification bonus is still available. Free; needs an API key. |\n\nEvery tool is read-only and annotated `readOnlyHint: true`, so clients that confirm side-effecting tools can run these without prompting. Full input schemas are returned by `tools/list` and published in the [server card](https://cart-route.com/.well-known/mcp.json).\n\n## Which resources and prompts are there?\n\n- `cartroute://retailers`, `cartroute://categories`, `cartroute://pricing`: reference data as JSON resources.\n\n- Prompt `find_best_deal` (arguments `product`, optional `budget_usd`): instructs the model to search, compare on effective price, flag membership and eligibility requirements, and recommend one retailer with its reasoning.\n\n## What does a raw call look like?\n\n```\ncurl https://cart-route.com/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json, text/event-stream\" \\\n  -H \"Authorization: Bearer $CARTROUTE_API_KEY\" \\\n  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_products","arguments":{"query":"robot vacuum under $600","in_stock":true,"limit":3}}}'\n```\n\nThe result's `structuredContent` is the same envelope the REST search returns, and `content[0].text` carries it as JSON text for clients that only read text.\n\n## What happens when a tool fails?\n\nIt returns a normal result with `isError: true` and a JSON body using the REST error `code` values (`insufficient_credits`, `validation_error`, `not_found`). A missing key produces an `isError` result that says how to get one, so the model can explain the next step to its user. See [errors](https://cart-route.com/docs/errors).\n\n## Which protocol details should client authors know?\n\n- Transport: Streamable HTTP, stateless. `POST` carries JSON-RPC; responses are `application/json`. `GET /mcp` returns 405 because the server opens no server-initiated streams.\n\n- Protocol versions: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. The server echoes the client's requested version when supported, otherwise the newest.\n\n- Notifications (for example `notifications/initialized`) receive `202 Accepted` with no body. JSON-RPC batches are answered for older clients.\n\n- Authentication: a bearer API key in the `Authorization` header. An invalid key returns HTTP 401 with a `WWW-Authenticate` header.\n\n- Rate limits are shared with the REST API: 120 requests per minute per key."
}