Para desarrolladores y agentes

API y MCP para editar tu escaparate

Conecta Claude, ChatGPT, Cursor o tu propio script a tu escaparate de Mercader. Pueden leer y editar tu perfil, tus productos, tus eventos y tus enlaces, y cada cambio se publica al momento.

Crear un token en el panel Leer la guía paso a paso

Empieza en un minuto

Elige tu cliente. Con OAuth no copias ningún token: tu asistente abre la pantalla de permisos de Mercader y tú apruebas el acceso.

Claude.ai o ChatGPT

Añade un conector personalizado y pega esta 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 o tu propio código

Crea un token personal en el panel y envíalo como Bearer:

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

Autenticación

Todas las peticiones llevan la cabecera Authorization: Bearer <token>. Un token solo da acceso al escaparate de la persona que lo creó.

OAuth 2.1 (recomendado para asistentes)

Registro dinámico de clientes (RFC 7591) y código de autorización con PKCE S256. Solo clientes públicos, sin secreto.
Descubrimiento: el 401 del MCP incluye WWW-Authenticate con la URL de los metadatos del recurso protegido.
El token de acceso dura 1 hora y el de refresco 30 días. Cada refresco rota los dos.
Revocación (RFC 7009) en /oauth/revoke, o desde el panel en cualquier momento.

Tokens personales

Créalos en el panel, en Admin › Asistentes de IA. Empiezan por mk_live_ y solo se muestran una vez.
No caducan: revócalos desde el panel cuando ya no los uses.
Útiles para scripts, curl y clientes que no admiten OAuth.

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

Permisos (scopes)

Permisos (scopes)
Permiso	Qué hace
`profile:write`	Nombre, presentación, color, idioma, moneda, logo, portada y enlaces.
`catalog:write`	Productos, eventos y ferias, y sus imágenes.

API REST

JSON sobre HTTPS. Los campos que no envías no cambian; una cadena vacía borra un campo opcional.

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

API REST
Método	Ruta	Permiso	Qué hace
GET	`/me`	cualquiera	Perfil, plan y límites, productos, eventos y enlaces, con sus id.
PATCH	`/profile`	`profile:write`	Cambia nombre, presentación, color, idioma, país, moneda, logo o portada.
GET	`/products`	cualquiera	Lista los productos.
POST	`/products`	`catalog:write`	Crea un producto (name y price obligatorios).
PATCH	`/products/{id}`	`catalog:write`	Cambia precio, foto, disponibilidad u otros campos.
DELETE	`/products/{id}`	`catalog:write`	Borra un producto.
GET	`/events`	cualquiera	Lista los eventos y ferias.
POST	`/events`	`catalog:write`	Crea un evento (title y start_date en ISO 8601).
PATCH	`/events/{id}`	`catalog:write`	Cambia un evento.
DELETE	`/events/{id}`	`catalog:write`	Borra un evento.
GET	`/social-links`	cualquiera	Lista los enlaces sociales y de contacto.
POST	`/social-links`	`profile:write`	Añade un enlace (Instagram, WhatsApp, Website, Email…).
PATCH	`/social-links/{id}`	`profile:write`	Cambia un enlace.
DELETE	`/social-links/{id}`	`profile:write`	Borra un enlace.
POST	`/uploads`	según el tipo	Devuelve una URL firmada para subir una imagen.

Ejemplo: crear un producto

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"}'

Esquemas completos en la especificación OpenAPI 3.1

Subir imágenes

Pide una subida con kind (product, event, avatar o header) y content_type (image/jpeg, image/png o image/webp).
Envía los bytes de la imagen con PUT a upload_url. La URL caduca en 2 horas.
Usa public_url como image_url del producto o del evento, o como avatar_url o header_url del perfil.

Servidor MCP

Streamable HTTP, sin estado. Mismas operaciones, validación y límites que la API REST.

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

Servidor MCP
Herramienta	Qué hace
`get_my_storefront`	Estado actual del escaparate: perfil, URL pública, plan, límites y todos los elementos con sus id.
`update_profile`	Cambia solo los campos del perfil que recibe. La dirección (slug) no se puede cambiar.
`create_productupdate_productdelete_productcreate_eventupdate_eventdelete_eventcreate_social_linkupdate_social_linkdelete_social_link`	Crea, cambia o borra productos, eventos y enlaces. Las herramientas de borrado están marcadas como destructivas.
`create_image_upload`	Prepara la subida de una imagen y devuelve upload_url y public_url.

MCP público de solo lectura

Para buscar en todos los escaparates publicados, sin autenticación:

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

Límites y errores

120 peticiones por minuto y token. Al superarlo, 429 con Retry-After.
Los límites de tu plan se aplican igual que en el panel: al llegar al máximo, 403 plan_limit.
Las respuestas llevan Cache-Control: no-store.

Formato de error

Todos los errores devuelven un JSON con un código estable y una descripción legible:

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

Formato de error
Código	HTTP	Significado
`invalid_input`	400	Falta un campo, sobra uno o tiene un formato no válido.
`invalid_token`	401	Token ausente, desconocido, revocado o caducado.
`insufficient_scope`	403	El token no tiene el permiso que pide la operación.
`plan_limit`	403	Se ha alcanzado el límite del plan o la prueba ha terminado.
`not_found`	404	El elemento no existe en tu escaparate.
`no_profile`	409	La cuenta aún no ha terminado el onboarding.
`rate_limited`	429	Demasiadas peticiones en el último minuto.

Seguridad y privacidad

Guardamos solo un hash de cada token. Si lo pierdes, crea otro.
Un token no puede leer tus contactos, tus reseñas ni tu facturación, ni cambiar la dirección de tu escaparate.
Los cambios se publican al momento para tus clientes: pide a tu asistente que confirme antes de borrar.

¿Todavía no tienes escaparate?

Crea el tuyo y conecta tu asistente después. Mercader tiene 14 días de prueba.

Crear mi escaparate