---
title: "Mercader API and MCP for AI agents"
description: "Reference for the Mercader REST API and MCP server: OAuth 2.1, personal tokens, endpoints, tools, image uploads, limits and errors."
url: https://www.mercader.app/en/developers
language: en
---

# 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: https://app.mercader.app/admin?tab=agents
- Read the step-by-step guide: https://www.mercader.app/en/blog/manage-your-storefront-with-ai.md
- OpenAPI: https://web.mercader.app/api/v1/openapi.json

## 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

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

### Cursor (~/.cursor/mcp.json)

```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:

```bash
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.
- https://web.mercader.app/.well-known/oauth-protected-resource
- https://web.mercader.app/.well-known/oauth-authorization-server

### 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.

### 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.

Base URL: `https://web.mercader.app/api/v1`

| 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

```bash
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](https://web.mercader.app/api/v1/openapi.json)

## Uploading images

1. Request an upload with kind (product, event, avatar or header) and content_type (image/jpeg, image/png or image/webp).
2. PUT the image bytes to upload_url. The URL expires after 2 hours.
3. 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
```

| 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_product`, `update_product`, `delete_product`, `create_event`, `update_event`, `delete_event`, `create_social_link`, `update_social_link`, `delete_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:

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

| 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](https://app.mercader.app/auth?mode=signup&utm_source=mercader-web&utm_medium=llms&utm_campaign=llms)