For developers and agents

API and MCP to edit your storefront

Connect Claude, ChatGPT, Cursor or your own script to your Mercader storefront. They can read and edit your profile, products, events and links, and every change goes live immediately.

Create a token in the dashboard Read the step-by-step guide

Get started in a minute

Pick your client. With OAuth you never copy a token: your assistant opens Mercader's permission screen and you approve access.

Claude.ai or ChatGPT

Add a custom connector and paste this URL:

https://web.mercader.app/api/mcp/me

Claude Code

claude mcp add --transport http mercader https://web.mercader.app/api/mcp/me

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "mercader": {
      "url": "https://web.mercader.app/api/mcp/me"
    }
  }
}

curl or your own code

Create a personal token in the dashboard and send it as a Bearer token:

curl https://web.mercader.app/api/v1/me \
  -H "Authorization: Bearer mk_live_…"

Authentication

Every request carries the header Authorization: Bearer <token>. A token only gives access to the storefront of the person who created it.

OAuth 2.1 (recommended for assistants)

Dynamic client registration (RFC 7591) and authorization code with PKCE S256. Public clients only, no secret.
Discovery: the MCP 401 response includes WWW-Authenticate with the protected resource metadata URL.
Access tokens last 1 hour and refresh tokens 30 days. Each refresh rotates both.
Revocation (RFC 7009) at /oauth/revoke, or from the dashboard at any time.

Personal tokens

Create them in the dashboard under Admin › AI assistants. They start with mk_live_ and are shown only once.
They don't expire: revoke them from the dashboard when you stop using them.
Handy for scripts, curl and clients without OAuth support.

https://web.mercader.app/.well-known/oauth-protected-resource
https://web.mercader.app/.well-known/oauth-authorization-server

Scopes

Scopes
Scope	What it does
`profile:write`	Name, bio, colour, language, currency, logo, cover image and links.
`catalog:write`	Products, events and markets, and their images.

REST API

JSON over HTTPS. Fields you don't send stay as they are; an empty string clears an optional field.

https://web.mercader.app/api/v1

REST API
Method	Path	Scope	What it does
GET	`/me`	any	Profile, plan and limits, products, events and links, with their ids.
PATCH	`/profile`	`profile:write`	Changes name, bio, colour, language, country, currency, logo or cover image.
GET	`/products`	any	Lists products.
POST	`/products`	`catalog:write`	Creates a product (name and price required).
PATCH	`/products/{id}`	`catalog:write`	Changes price, photo, availability or other fields.
DELETE	`/products/{id}`	`catalog:write`	Deletes a product.
GET	`/events`	any	Lists events and markets.
POST	`/events`	`catalog:write`	Creates an event (title and start_date in ISO 8601).
PATCH	`/events/{id}`	`catalog:write`	Changes an event.
DELETE	`/events/{id}`	`catalog:write`	Deletes an event.
GET	`/social-links`	any	Lists social and contact links.
POST	`/social-links`	`profile:write`	Adds a link (Instagram, WhatsApp, Website, Email…).
PATCH	`/social-links/{id}`	`profile:write`	Changes a link.
DELETE	`/social-links/{id}`	`profile:write`	Deletes a link.
POST	`/uploads`	depends on kind	Returns a signed URL to upload an image.

Example: create a product

curl -X POST https://web.mercader.app/api/v1/products \
  -H "Authorization: Bearer mk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name": "Taza de gres", "price": 22, "description": "300 ml"}'

Full schemas in the OpenAPI 3.1 specification

Uploading images

Request an upload with kind (product, event, avatar or header) and content_type (image/jpeg, image/png or image/webp).
PUT the image bytes to upload_url. The URL expires after 2 hours.
Use public_url as the image_url of a product or event, or as the profile's avatar_url or header_url.

MCP server

Streamable HTTP, stateless. Same operations, validation and limits as the REST API.

https://web.mercader.app/api/mcp/me

MCP server
Tool	What it does
`get_my_storefront`	Current state of the storefront: profile, public URL, plan, limits and every item with its id.
`update_profile`	Changes only the profile fields it receives. The address (slug) cannot be changed.
`create_productupdate_productdelete_productcreate_eventupdate_eventdelete_eventcreate_social_linkupdate_social_linkdelete_social_link`	Creates, changes or deletes products, events and links. Delete tools are annotated as destructive.
`create_image_upload`	Prepares an image upload and returns upload_url and public_url.

Public read-only MCP

To search every published storefront, without authentication:

https://web.mercader.app/api/mcp

Limits and errors

120 requests per minute per token. Beyond that, 429 with Retry-After.
Your plan limits apply just like in the dashboard: at the maximum you get 403 plan_limit.
Responses carry Cache-Control: no-store.

Error format

Every error returns JSON with a stable code and a readable description:

{
  "error": "plan_limit",
  "error_description": "…"
}

Error format
Code	HTTP	Meaning
`invalid_input`	400	A field is missing, unknown or badly formatted.
`invalid_token`	401	Token missing, unknown, revoked or expired.
`insufficient_scope`	403	The token lacks the scope the operation needs.
`plan_limit`	403	The plan limit was reached or the trial has ended.
`not_found`	404	The item doesn't exist in your storefront.
`no_profile`	409	The account hasn't finished onboarding yet.
`rate_limited`	429	Too many requests in the last minute.

Security and privacy

We store only a hash of each token. If you lose one, create another.
A token cannot read your contacts, reviews or billing, nor change your storefront address.
Changes go live for your customers immediately: ask your assistant to confirm before deleting.

No storefront yet?

Create yours and connect your assistant afterwards. Mercader comes with a 14-day trial.

Create my storefront