Mareco API and MCP server
Everything the store knows, as JSON: the curated catalog with live supplier pricing, stock and production dates, logo uploads and AI photo previews, quotes, approvals and order status. The same operations are exposed twice: a REST API for programs, and an MCP server so an AI agent can use Mareco as a tool set.
Quick start
- Sign in and create a key under Account → API. Keys start with
mk_and are shown once. - Send it on every request:
Authorization: Bearer mk_… - Start at
GET https://mareco.com/api/v1: it lists the endpoints and the guidance below.
curl -H "Authorization: Bearer mk_..." "https://mareco.com/api/v1/products?q=hoodie&use_case=team-apparel" curl -H "Authorization: Bearer mk_..." "https://mareco.com/api/v1/products/hitpromo:S700" curl -H "Authorization: Bearer mk_..." "https://mareco.com/api/v1/products/hitpromo:S700/price?quantity=48&location_id=243&method_id=651480123"
Endpoints
| Method and path | Scope | What it does |
|---|---|---|
GET /api/v1 | none | Discovery: endpoints, links, agent guidance. |
GET /api/v1/products | read | Search. q words, use_case, category, limit (≤50), offset. |
GET /api/v1/products/{key} | read | Detail: parts (color, size, part_id), decoration locations and methods with ids and imprint areas, price ladder, minimum. |
GET /api/v1/products/{key}/price | read | quantity, optional location_id, method_id, units. Decorated price with setup and run charges, from the same code as the cart. |
GET /api/v1/products/{key}/stock | read | Live stock per part from the supplier (cached up to 10 minutes). |
GET /api/v1/products/{key}/inhands | read | Earliest in-hands date; optional need_by=YYYY-MM-DD says whether it is met. |
GET /api/v1/use-cases | read | The five ways technology companies buy. |
POST /api/v1/budget-plans | read | {budget_usd, people, use_case?, wants?} → up to three priced bundles with per-person cost and in-hands dates. |
GET /api/v1/artwork | read | Logos this account can use: brand kit and uploads. |
POST /api/v1/artwork | write | Upload a logo (multipart, field file: PNG, JPG, SVG, PDF, AI) → artwork_id. |
POST /api/v1/renders | write | {key, part_id, location_id, method_id, artwork_id, variant?} → AI photo of the logo on the product (about 30 s). Returns a url and a render_id. |
POST /api/v1/quotes | write | {lines:[{key, part_id, quantity, location_id, method_id, units?, artwork_id?, render_id?}], name?, company?, email?, note?} → a saved, priced quote with a url where a person completes the order. |
GET /api/v1/quotes, /quotes/{id} | write | This account's quotes. |
POST /api/v1/approvals | write | {quote_id, approver_name, approver_email?, message?} → approval link; the approver answers with one click and the requester is emailed. |
GET /api/v1/approvals/{id} | write | Approval status. |
GET /api/v1/orders, /orders/{id} | orders | This account's orders; one order includes live supplier status and tracking. |
GET /api/v1/agents | read | What the agents did this week (the sanitized numbers behind /agents). |
GET /api/v1/me | none | The key, its scopes, remaining photo previews today, and the account. |
Machine-readable description: OpenAPI 3.1. Errors are {"error":{"code","message"}} with 401, 403, 404, 422, 429 or 5xx. Every key is limited to 120 requests a minute (X-RateLimit-Remaining header) and 200 photo previews a day. Product keys look like hitpromo:S700; URL-encode the colon or send it as is.
What the API does not do
It never places or pays for an order. A quote's url is the handoff: a person opens it, reviews the items with their logo on them, and pays by card or on terms. That is deliberate. The agents that run Mareco earn autonomy one action at a time, and spending a customer's money is the last rung.
MCP server
Mareco runs a Model Context Protocol server at https://mareco.com/mcp over Streamable HTTP, authenticated with the same Bearer key. It is stateless: POST a JSON-RPC 2.0 request and read the JSON response. It exposes the operations above as tools (search_products, get_product, price_quote, check_stock, inhands_date, list_use_cases, plan_budget, list_logos, photo_preview, create_quote, get_quote, request_approval, list_orders, order_status, agents_report) and returns its guidance in the initialize response, so a well-behaved agent knows the rules before it calls anything.
# Claude Code
claude mcp add --transport http mareco https://mareco.com/mcp --header "Authorization: Bearer mk_..."
# Claude Desktop or any stdio-only client, via the mcp-remote bridge
{ "mcpServers": { "mareco": { "command": "npx", "args": ["mcp-remote", "https://mareco.com/mcp", "--header", "Authorization: Bearer mk_..."] } } }
# Raw
curl -X POST https://mareco.com/mcp -H "Authorization: Bearer mk_..." -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_products","arguments":{"query":"tumbler"}}}'
Guidance for agents
PromoStandards
Distributor systems that already speak the industry standard can use Mareco as a supplier: SOAP services for Product Data, Media Content, Pricing and Configuration, Inventory, Purchase Order, Order Status and Shipment Notification, with the same API key as the password. See the PromoStandards directory.
This guidance is also served at /llms.txt and inside GET /api/v1.