DuckHub

Conéctate mediante MCP

MCP (Protocolo de Contexto de Modelo) es el estándar abierto que los asistentes de IA utilizan para trabajar con servicios externos. En lugar de escribir solicitudes HTTP contra la API REST, tu agente de IA (Claude, Cursor, …) ve DuckHub como un conjunto de herramientas tipadas y listas para usar — build_menu, set_image, publish_menu — y puede construir y gestionar un menú completo a partir de una conversación.

El servidor MCP de DuckHub está alojado — no hay nada que instalar ni ejecutar. Añades una URL a tu cliente de IA y te autenticas con la misma clave de API dk_live_ que usa la API REST.

Endpoint

POST https://mcp.duck-hub.com/mcp

Si el subdominio mcp. aún no es resoluble en tu red, el mismo servidor también está disponible en https://api.duck-hub.com/mcp.

Transporte: HTTP Streamable (sin estado). Autenticación: el encabezado Authorization: Bearer dk_live_... — el servidor lo reenvía a la API en cada llamada de herramienta, por lo que se aplican sin cambios los límites de tasa, límites de plan y el registro de auditoría habituales.

Añádelo a tu cliente

Obtén tu clave de API desde la app de DuckHub → página Integraciones, luego:

claude mcp add --transport http duckhub https://mcp.duck-hub.com/mcp \
  --header "Authorization: Bearer dk_live_your_api_key"

claude.ai (web) y ChatGPT conectan servidores MCP personalizados mediante OAuth — sin necesidad de pegar una clave de API. Añade la URL del servidor, inicia sesión con tu cuenta de DuckHub, elige tu local y permite el acceso. Consulta Conectar con OAuth para ver el tutorial completo.

Acceso de solo lectura

La página de Integraciones también puede emitir una clave de solo lectura (mismo formato dk_live_). Con ella, todas las herramientas de lectura funcionan con normalidad y todas las herramientas de escritura fallan con 403 READ_ONLY_KEY — la API rechaza la escritura antes de tocar nada. Las herramientas de escritura también están marcadas con anotaciones MCP estándar (readOnlyHint / destructiveHint), para que los clientes bien comportados puedan filtrarlas o confirmarlas de antemano. Usa una clave de solo lectura para agentes que deban analizar el menú pero nunca modificarlo.

Qué cubren las herramientas

Las 42 herramientas envuelven la API REST v1 — mismo comportamiento, mismos límites:

Grupo	Herramientas
Descubrir y leer	get_reference, get_menu, list_products, get_product, list_categories, list_publications, get_audit_log
Construir el menú	build_menu (sincronización masiva), set_product, delete_product, set_modifier_group, delete_modifier_group, list_modifier_groups
Configuración	get_settings + 7 herramientas update_* con ámbito de tarea (configuración)
Medios	set_image — producto / banner / historia / logo (medios)
Traducciones	set_translations, get_translations (traducciones)
Merchandising	promociones / banners / historias / tablas — list_* / set_* / delete_* (merchandising)
Publicar	publish_menu, rollback_publish, cleanup_menu (publicación)
Pedidos	list_orders, get_order, update_order_status — planes de pago (pedidos)

Los agentes deben llamar a get_reference primero: devuelve cada valor de enumeración permitido, los límites del plan de tu local y el uso actual, y las convenciones monetarias — todo lo que las demás herramientas asumen.

Errores comunes de los agentes

• El dinero son enteros en unidades menores — 12.50 se envía como 1250 (kopeks/céntimos). En todas partes.
• Nada es visible para los clientes hasta que publicas. build_menu y similares editan el borrador; publish_menu lo hace público (y guarda una instantánea de reversión).
• Prueba primero en seco. build_menu y cleanup_menu aceptan dryRun: true — validación completa y una vista previa sin escrituras. Úsalo antes de cargas grandes o la primera vez.
• Los arrays de cleanup_menu son listas de conservación — todo lo no listado se oculta o elimina. Lee la descripción de la herramienta con atención.
• Las herramientas de pedidos requieren un plan de pago — en el plan gratuito devuelven 403 PAID_PLAN_REQUIRED.
• Las herramientas compuestas realizan varias llamadas a la API internamente — set_promotion (una por elemento) y las herramientas de configuración update_* (lectura + escritura) cuentan cada una varias solicitudes hacia el presupuesto de tasa de tu local.

Los errores siguen el sobre de error estándar y cada error de herramienta incluye una breve pista de recuperación, por lo que los agentes normalmente pueden corregir sus propios errores.