Connect via MCP

MCP (Model Context Protocol) is the open standard AI assistants use to work with external services. Instead of writing HTTP requests against the REST API, your AI agent (Claude, Cursor, …) sees DuckHub as a set of ready-made, typed tools — build_menu, set_image, publish_menu — and can build and manage a complete menu from a conversation.

The DuckHub MCP server is hosted — there is nothing to install or run. You add one URL to your AI client and authenticate with the same dk_live_ API key the REST API uses.

Endpoint#

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

If the mcp. subdomain is not yet resolvable in your network, the same server is also reachable at https://api.duck-hub.com/mcp.

Transport: Streamable HTTP (stateless). Authentication: the Authorization: Bearer dk_live_... header — the server forwards it to the API on every tool call, so all the usual rate limits, plan limits and the audit log apply unchanged.

Add it to your client#

Get your API key from the DuckHub app → Integrations page, then:

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

# ~/.codex/config.toml
[mcp_servers.duckhub]
url = "https://mcp.duck-hub.com/mcp"
http_headers = { "Authorization" = "Bearer dk_live_your_api_key" }

// .cursor/mcp.json — keep the key in an env var, not in the file
{
  "mcpServers": {
    "duckhub": {
      "url": "https://mcp.duck-hub.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:DUCKHUB_API_KEY}"
      }
    }
  }
}

// claude_desktop_config.json — Desktop connects remote servers
// through the mcp-remote bridge (requires Node.js)
{
  "mcpServers": {
    "duckhub": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.duck-hub.com/mcp",
        "--header",
        "Authorization: Bearer dk_live_your_api_key"
      ]
    }
  }
}

// Claude API — MCP connector block in a Messages request
{
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://mcp.duck-hub.com/mcp",
      "name": "duckhub",
      "authorization_token": "dk_live_your_api_key"
    }
  ]
}

ChatGPT and claude.ai (web) connect through OAuth — no API key to paste. In ChatGPT, open Plugins, find the Duckhub QR Menu app and click Connect; on claude.ai, add a custom connector with the server URL. Then sign in with your DuckHub account, pick your venue, and allow access. See Connect with OAuth for the full walkthrough.

Every other agent (Claude Code, Codex, Cursor, Claude Desktop, your own scripts) connects with an API key as shown above — there is no sign-in flow for them.

Read-only access#

The Integrations page can also issue a read-only key (same dk_live_ format). With it every read tool works normally, and every write tool fails with 403 READ_ONLY_KEY — the API refuses the write before touching anything. Write tools are also marked with standard MCP annotations (readOnlyHint / destructiveHint), so well-behaved clients can filter or confirm them up front. Use a read-only key for agents that should analyse the menu but never change it.

What the tools cover#

All 42 tools wrap the v1 REST API — same behavior, same limits:

Agents should call get_reference first: it returns every allowed enum value, your venue's plan limits and current usage, and the money conventions — everything the other tools assume.

Things agents get wrong#

• Money is integers in minor units — 12.50 is sent as 1250 (kopecks/cents). Everywhere.
• Nothing is guest-visible until you publish. build_menu and friends edit the draft; publish_menu makes it live (and keeps a rollback snapshot).
• Dry-run first. build_menu and cleanup_menu accept dryRun: true — full validation and a preview with zero writes. Use it before large or first-time payloads.
• cleanup_menu arrays are KEEP-lists — everything not listed gets hidden or deleted. Read the tool description carefully.
• Orders tools need a paid plan — on the free plan they return 403 PAID_PLAN_REQUIRED.
• Composite tools make several API calls internally — set_promotion (one per item) and the settings update_* tools (read + write) each count multiple requests toward your venue's rate budget.

Errors follow the standard error envelope and every tool error includes a short recovery hint, so agents can usually fix their own mistakes.