Owner MCP reference

The owner MCP server lives at https://mcp.qaema.ai. Connect it as described in Connect your agent; every call below runs as you, through the scopes you granted at connection time.

Tools by scope

A tool refuses to run outside its granted scope with missing scope <scope> — reconnect the agent and grant it <scope>.

`venue:read`

Tool	What it does
`list_venues`	List the venues in your organization.
`get_analytics`	Scans, visitors, view→add, sources, languages, badge lift and weekly insights.
`list_feedback`	Diners’ ratings and comments, with a summary.
`get_billing_status`	Your plan and subscription state.
`list_plans`	Every plan’s price and entitlements.
`list_docs`	List this knowledge base’s pages in one language.
`search_docs`	Search this knowledge base; returns matching pages with a snippet.
`get_doc`	Read one knowledge-base page as markdown, by slug.

`venue:write`

Tool	What it does
`create_venue`	Create a venue with its empty draft menu.
`update_venue`	Update profile, contact, hours, links, delivery, pickup, follow block. An empty reserve or pickup WhatsApp or phone number uses the venue’s contact number; a save with neither is refused.
`generate_qr`	Create table, pickup or delivery QR codes.
`mark_feedback_read`	Mark feedback rows read.

`menu:read`

Tool	What it does
`get_menu`	Read the draft menu, with sections and items.
`get_change_log`	Recent changes by agents and people, with before/after.
`list_unavailable_items`	Items currently sold out, with when they return and who took them out.
`audit_menu`	Find missing calories, allergens, photos, translations, duplicates.
`get_theme_suggestions`	Rules-based template suggestion from menu size and photo coverage.

`menu:write`

Tool	What it does
`import_menu`	Stage a menu extracted from a photo, PDF, website or Instagram. Nothing goes live.
`confirm_import`	Apply a staged import to the draft, with corrections.
`discard_import`	Discard a staged import without applying it.
`publish_menu`	Publish the draft menu as a new version.
`unpublish_menu`	Take the menu offline (back to draft).
`undo_change`	Revert one change by id.
`upsert_sections`	Create or rename sections.
`upsert_items`	Create or update items. On an update, `null` clears the price, compare-at price, calories or description.
`delete_items`	Soft-delete items (undoable).
`set_allergens`	Replace one item’s allergens, may-contain list and dietary tags.
`set_item_badges`	Set up to two badges (`new`, `offer`) on items.
`set_item_contexts`	Choose where items appear: dine-in, pickup, delivery.
`upload_media`	Attach a photo to an item or set the venue logo.
`set_item_availability`	Mark items or sections sold out, or bring them back. Live within 30 seconds.
`set_theme`	Set the venue’s template, colors, fonts, radius and layout.

Bookings tools

Qaema Book tools work only on a venue where Book is enabled; every call checks that first.

`book:read`

Tool	What it does
`get_availability`	Free/taken/closed/past slots for a venue on one day.
`list_bookings`	List bookings for a venue, newest start first.

`book:write`

Tool	What it does
`create_booking`	Book a time for a guest. Idempotent by `command_id`.
`cancel_booking`	Cancel a booking; refused on a stale `expected_revision`.
`claim_security`	Keep part of a place booking’s security deposit, from check-out until 48 hours after; the rest is refunded to the guest at once.
`set_book_settings`	Update booking settings (slot interval, lead time, prayer pauses, more).
`block_time`	Block a time range for one resource or the whole venue.
`add_service`	Add a bookable service: name, duration, price.
`add_resource`	Add a bookable resource (staff, bay, court, team, room or place).

`dry_run`

update_venue, generate_qr, import_menu, discard_import, publish_menu, unpublish_menu, undo_change and upsert_items accept dry_run: true to preview the result — the diff, the count, or what would be discarded — without writing anything.

Widgets

Three tools carry an interactive widget for clients that support MCP Apps, alongside the plain tool result every client gets:

import_menu → Import Review (ui://qaema/import-review)
set_theme → Theme Preview (ui://qaema/theme-preview)
get_analytics → Analytics (ui://qaema/analytics)

A client without MCP Apps support still gets the full answer — the same text summary and structured JSON every other tool returns — it just doesn’t render the inline widget; open the equivalent dashboard page instead (/app/imports/{id}, /app/theme, /app/analytics).

Prompts

The server registers two prompts your client can offer as a starting point: import_menu_from_file (turning a menu photo or PDF into an import_menu call) and import_menu_from_instagram (turning your own Instagram account into one).

Rate limits

The owner MCP route itself carries no rate limit — access is gated by your OAuth token instead. (Only the public menu MCP that a visitor’s own assistant reaches at {slug}.qaema.ai/mcp is rate-limited, 60 requests a minute per address.)

Undo

undo_change reverts an agent’s write exactly like a dashboard edit — both go through the same change log, and both are undoable except for the few actions marked without an inverse (see Undo and the change log).

Access and photo imports

The owner connector requires a current owner or manager membership as well as the granted scopes. Staff accounts cannot use this connector. A role downgrade or removal stops subsequent calls even if the token has not expired.

For photos, send base64 with the image MIME type (JPEG, PNG or WebP, up to 10 MB). Remote source_url imports work only from an image origin approved by the platform operator, with no redirects. If a source is rejected, upload the owner’s photo directly or ask your assistant to send it as base64. Downloads have size and time limits; a rejected import stores no photo.