@cresva/acp-mcp

MCP server for the Cresva ACP storefront API. Wraps the Agent Commerce Protocol v2.0 endpoints so any MCP-compatible AI (Claude Desktop, Cursor, Windsurf, etc.) can discover brands, search and compare products, negotiate prices, and check trust scores.

Tools

| Tool | Backend | Auth | |---|---|---| | discover_storefront(brand_id) | GET /.well-known/acp.json?brand=<id> | public | | search_products(brand_id, query, …) | GET /api/storefront/<id>/search?q=… | public (rate-limited) | | list_products(brand_id, page?, limit?) | GET /api/storefront/<id>/products | public (rate-limited) | | get_product(brand_id, product_id) | GET /api/storefront/<id>/products/<pid> | public (rate-limited) | | negotiate_price(brand_id, product_id, offered_price, …) | POST /api/storefront/<id>/negotiate | public (rate-limited) | | get_trust_score(brand_id) | GET /api/storefront/<id>/trust | public (rate-limited) | | compare_products(brand_id, product_ids[]) | GET /api/storefront/<id>/compare?ids=… | public (rate-limited) |

All endpoints accept anonymous traffic but rate-limit by IP at ~10 req/min. Set CRESVA_API_KEY to lift the limit to your key tier.

Try it

The canonical demo brand is demo_acp_store_v1 ("ACP Demo Store") — a curated catalog of sneakers, headphones, sunglasses, and packs. Use it for first-run smoke tests:

discover_storefront  brand_id=demo_acp_store_v1
list_products        brand_id=demo_acp_store_v1
search_products      brand_id=demo_acp_store_v1  query="marathon shoes"
get_trust_score      brand_id=demo_acp_store_v1
negotiate_price      brand_id=demo_acp_store_v1  product_id=demo_prod_runner_pro_x  offered_price=169

The demo brand has a real negotiation policy configured: offers ≥ $166.47 (≈93% of $179 list) auto-accept with a real order reference, mid-range offers get a counter at $164, and offers below ~$130 reject with reason below_margin. Try offered_price=149 for a counter or 100 for a rejection.

Install

npm install -g @cresva/acp-mcp

Claude Desktop config

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or the equivalent path on your OS):

{
  "mcpServers": {
    "cresva-acp": {
      "command": "npx",
      "args": ["-y", "@cresva/acp-mcp"],
      "env": {
        "CRESVA_API_KEY": "pk_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. The seven tools above should appear in the tools picker (the slider icon).

Configuration

| Env var | Default | Purpose | |---|---|---| | CRESVA_API_KEY | (unset) | Bearer key from your Cresva storefront dashboard. Optional — anonymous traffic works at a lower rate limit. | | CRESVA_API_BASE | https://api.cresva.ai | Override the base URL (useful for staging or local dev, e.g. http://localhost:3000). | | CRESVA_TIMEOUT_MS | 10000 | Outbound request timeout in milliseconds. |

Example: end-to-end shopping conversation

User: "Find me sneakers under $200 from brand cmliyay3y0006jp04d7wfeocv. I'd pay $150 for the top result if that's possible."

Expected tool sequence:

1. discover_storefront — Claude calls this first to confirm the brand supports search and negotiate.

   { "brand_id": "cmliyay3y0006jp04d7wfeocv" }

   Returns the manifest with capabilities: ["search", …, "negotiate", …].

2. search_products — query the catalog with the user's natural-language ask.

   {
     "brand_id": "cmliyay3y0006jp04d7wfeocv",
     "query": "sneakers",
     "price_max": 200,
     "limit": 5
   }

   Returns ranked product cards. Claude picks the top result.

3. negotiate_price — initiate a negotiation at the user's target price.

   {
     "brand_id": "cmliyay3y0006jp04d7wfeocv",
     "product_id": "<from-step-2>",
     "offered_price": 150,
     "quantity": 1,
     "message": "User has a $150 budget for marathon training shoes."
   }

   Returns ACCEPTED, a COUNTERING price, or alternative deal structures (bundle, volume discount).

Claude then summarizes the result back to the user in plain English.

Development

npm install
npm run build       # tsc → build/index.js
npm run dev         # tsx watch
npm run inspect     # MCP Inspector UI

Pointing at a local Cresva dev server:

CRESVA_API_BASE=http://localhost:3000 npm start

License

MIT