MCP para desarrolladores

Tu asistente de IA lee nuestra documentación al día y, con una clave, trabaja sobre tu tienda.

Qué es

El MCP de Mandadito es un servidor Model Context Protocol que alojamos nosotros. Lo conectás a tu asistente de IA (Claude Code, Claude Desktop, Cursor, VS Code, Windsurf) y el asistente puede:

Leer la documentación al día: estas guías, la referencia de cada endpoint con sus esquemas, los códigos de error, los permisos y los eventos de webhooks. Sin clave.
Trabajar sobre tu tienda, si le das una clave: leer productos, stock, pedidos y clientes reales, probar escrituras y revisar qué pedidos de tu integración fallaron.

Es la misma API de siempre: el MCP llama a /partner/v1 con tu clave, así que valen los mismos permisos, límites, errores e Idempotency-Key que en estas guías.

Conectarlo

Entorno	URL del MCP	Clave
Producción	`https://api.mandaditoapp.com/mcp`	`mdt_live_`
Pruebas (sandbox)	`https://api-test.mandaditoapp.com/mcp`	`mdt_test_`

El transporte es Streamable HTTP. Sin el header Authorization tenés solo las herramientas de documentación; con la clave como bearer se suman las de la tienda.

La clave es una credencial: no la pongas en un archivo del proyecto que subas a git. Usá la configuración de usuario de tu cliente (abajo) o una variable de entorno.

Claude Code

claude mcp add --transport http mandadito https://api.mandaditoapp.com/mcp \
  --header "Authorization: Bearer mdt_live_..."

Sin --scope project, Claude Code lo guarda solo en tu computadora.

Cursor y Windsurf

En la configuración global (~/.cursor/mcp.json en Cursor, la de MCP en Windsurf):

{
  "mcpServers": {
    "mandadito": {
      "url": "https://api.mandaditoapp.com/mcp",
      "headers": { "Authorization": "Bearer mdt_live_..." }
    }
  }
}

VS Code

En la configuración de usuario (comando MCP: Open User Configuration). VS Code usa servers y type, y puede pedirte la clave en vez de guardarla:

{
  "inputs": [
    { "type": "promptString", "id": "mandadito-key", "description": "Clave de API de Mandadito", "password": true }
  ],
  "servers": {
    "mandadito": {
      "type": "http",
      "url": "https://api.mandaditoapp.com/mcp",
      "headers": { "Authorization": "Bearer ${input:mandadito-key}" }
    }
  }
}

Para usar solo la documentación, dejá afuera headers. Los conectores web que piden iniciar sesión (claude.ai, ChatGPT) todavía no están soportados: llegan con el inicio de sesión de Mandadito.

La clave del MCP

El dueño de la tienda la crea en el panel: Ajustes → API e integraciones → Conectar con IA. Es una clave de API común (plan Business), con dos atajos de permisos:

Solo lectura (recomendado para empezar): leer catálogo, stock, pedidos y clientes. El asistente no puede cambiar nada.
Lectura y escritura: además puede fijar stock, cambiar precios y dar de alta productos o clientes.

El panel te muestra la configuración lista para copiar. Podés revocar la clave cuando quieras y deja de funcionar al instante. Para integrar sin riesgo, pedinos una clave de pruebas y conectá el MCP de sandbox.

Herramientas

Documentación (sin clave):

Herramienta	Para qué
`search_documentation`	Buscar en las guías, los endpoints, los códigos de error, los permisos y los eventos
`get_guide`	Leer una guía o una sección
`list_endpoints` / `get_endpoint`	La lista de endpoints y la referencia completa de uno, con esquemas y un ejemplo en curl
`get_error_code`	Qué significa un código de error y si se reintenta
`list_scopes` / `list_webhook_topics`	Los permisos de una clave y los eventos de webhooks

Tienda (con clave, según sus permisos):

Herramienta	Para qué
`whoami`	La tienda, el entorno y los permisos de la clave. Es lo primero que llama el asistente
`list_products`, `get_inventory_levels`, `list_orders`, `list_customers`, …	Leer los datos reales de la tienda
`set_stock`, `adjust_stock`, `set_variant_prices`, `upsert_products`, …	Escribir, con la vista previa de abajo
`recent_api_requests`	Los últimos pedidos hechos con la clave y su status: para ver qué falló en tu integración
`list_webhook_deliveries`, `send_test_webhook`	Depurar tus webhooks
`call_api`	Cualquier otro endpoint documentado

Escrituras con vista previa

Con una clave de producción, ninguna escritura se aplica en la primera llamada. El MCP devuelve una vista previa (el pedido exacto que va a hacer y cuántos ítems toca) y un confirmToken, y le indica al asistente que te la muestre y espere tu OK antes de volver a llamar con el token y los mismos argumentos. Si cambian los argumentos, el token no sirve y no se escribe nada.

La vista previa es un freno para el asistente, no una firma tuya: un asistente que no sigue las instrucciones puede confirmar solo. Por eso, para empezar, usá una clave de solo lectura o una de pruebas, y dale una de escritura solo a un asistente en el que confíes.

El token vence a los 10 minutos y viaja como Idempotency-Key: si el asistente reintenta la confirmación, la API devuelve la primera respuesta en vez de escribir dos veces. Con una clave de pruebas, las escrituras se aplican directo.

Qué pedirle

"Leé la guía de sincronización y escribime en Python un script que suba el stock desde este CSV, con reintentos y Idempotency-Key."
"¿Por qué mi ERP recibe 422 desde ayer? Mirá los pedidos recientes de la clave."
"Listá los productos sin externalId y proponé cómo mapearlos con los códigos de mi sistema."
"Armame el receptor de webhooks en Node que verifique la firma y procese order.paid."

Seguí con Primeros pasos si todavía no hiciste tu primera llamada, o con Autenticación para los permisos.