DuckHub

Conecte-se via MCP

MCP (Model Context Protocol) é o padrão aberto que assistentes de IA usam para trabalhar com serviços externos. Em vez de escrever requisições HTTP contra a API REST, seu agente de IA (Claude, Cursor, …) enxerga o DuckHub como um conjunto de ferramentas prontas e tipadas — build_menu, set_image, publish_menu — e pode criar e gerenciar um cardápio completo a partir de uma conversa.

O servidor MCP do DuckHub é hospedado — não há nada para instalar ou executar. Você adiciona uma URL ao seu cliente de IA e autentica com a mesma chave de API dk_live_ que a API REST usa.

Endpoint

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

Se o subdomínio mcp. ainda não for resolvível na sua rede, o mesmo servidor também está acessível em https://api.duck-hub.com/mcp.

Transporte: Streamable HTTP (stateless). Autenticação: o cabeçalho Authorization: Bearer dk_live_... — o servidor o encaminha para a API em cada chamada de ferramenta, então todos os limites de taxa, limites do plano e o log de auditoria usuais se aplicam sem alterações.

Adicione ao seu cliente

Obtenha sua chave de API no app DuckHub → página Integrações, depois:

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

claude.ai (web) e ChatGPT conectam servidores MCP personalizados via OAuth — sem chave de API para colar. Adicione a URL do servidor, entre com sua conta DuckHub, escolha seu estabelecimento e permita o acesso. Veja Conectar com OAuth para o passo a passo completo.

Acesso somente leitura

A página de Integrações também pode emitir uma chave somente leitura (mesmo formato dk_live_). Com ela, toda ferramenta de leitura funciona normalmente, e toda ferramenta de escrita falha com 403 READ_ONLY_KEY — a API recusa a escrita antes de tocar em qualquer coisa. As ferramentas de escrita também são marcadas com anotações MCP padrão (readOnlyHint / destructiveHint), para que clientes bem-comportados possam filtrá-las ou confirmá-las antecipadamente. Use uma chave somente leitura para agentes que devem analisar o cardápio, mas nunca alterá-lo.

O que as ferramentas cobrem

Todas as 42 ferramentas encapsulam a API REST v1 — mesmo comportamento, mesmos limites:

Grupo	Ferramentas
Descobrir e ler	get_reference, get_menu, list_products, get_product, list_categories, list_publications, get_audit_log
Montar o cardápio	build_menu (em massa sync), set_product, delete_product, set_modifier_group, delete_modifier_group, list_modifier_groups
Configurações	get_settings + 7 ferramentas update_* com escopo de tarefa (settings)
Mídia	set_image — produto / banner / story / logo (media)
Traduções	set_translations, get_translations (translations)
Merchandising	promoções / banners / stories / tabelas — list_* / set_* / delete_* (merchandising)
Publicar	publish_menu, rollback_publish, cleanup_menu (publish)
Pedidos	list_orders, get_order, update_order_status — planos pagos (orders)

Os agentes devem chamar get_reference primeiro: ela retorna todos os valores de enum permitidos, os limites do plano do seu estabelecimento e o uso atual, e as convenções monetárias — tudo o que as outras ferramentas assumem.

Erros comuns dos agentes

• Dinheiro é inteiro em unidades menores — 12.50 é enviado como 1250 (centavos). Em todo lugar.
• Nada fica visível para os clientes até você publicar. build_menu e companheiras editam o rascunho; publish_menu o publica (e mantém um snapshot de rollback).
• Faça dry-run primeiro. build_menu e cleanup_menu aceitam dryRun: true — validação completa e uma prévia com zero escritas. Use antes de payloads grandes ou de primeira vez.
• Arrays cleanup_menu são listas de MANTER — tudo o que não estiver listado é ocultado ou excluído. Leia a descrição da ferramenta com atenção.
• As ferramentas de pedidos exigem um plano pago — no plano gratuito elas retornam 403 PAID_PLAN_REQUIRED.
• Ferramentas compostas fazem várias chamadas de API internamente — set_promotion (uma por item) e as ferramentas de configurações update_* (leitura + escrita) contam múltiplas requisições para o orçamento de taxa do seu estabelecimento.

Erros seguem o envelope de erro padrão e todo erro de ferramenta inclui uma dica curta de recuperação, para que os agentes geralmente consigam corrigir seus próprios erros.