Limitations, Tips & FAQ

The Headset MCP server puts live Headset data behind a conversation, and like any tool, it works best when you know its edges. This article covers what the connector can and can't do, how to get reliable answers, and answers to the questions we hear most.

What the connector is (and isn't)

It is a read-only window into your Headset data: sales, inventory, benchmarks, and (with the add-on) competitive menu intelligence, queried live each time you ask.

It isn't a replacement for Headset's apps. Dashboards, alerts, the reorder report, and data exports still live in Headset. And it never writes anything: no tool can change, delete, or create data in your account.

Known limitations

Answers depend on how the AI interprets your question. The AI chooses which tools to call and how to filter them. It's very good at this, but it can occasionally scope a question differently than you intended (a different time window, a broader store set). If a number matters, ask "what filters and time window did you use?" and it will tell you exactly. For high-stakes decisions, verify in Headset first.

One dimension at a time for breakdowns. Ranked breakdowns slice by a single dimension (top brands, top products, sales by store). Trends can add one more (monthly sales by category). If you need a three-way pivot, the AI will approximate it by running several queries and stitching them together, which works but takes longer.

Result caps. Breakdown and inventory queries return up to 500 rows per call, with sensible defaults (usually the top 50). For most questions this is plenty; "give me every SKU we've ever sold" is better served by an export from Headset.

No prescriptive reorder quantities. The inventory tools identify what's running low and how fast it's selling. They deliberately do not suggest order amounts; that's what the reorder report in Headset Retailer is for.

Benchmarks are monthly and trail the calendar. Benchmark questions are answered against the most recent fully-closed month, not today.

Competitive menu data is crawled. Menu coverage (with the Competitive Intelligence add-on) comes from crawling public e-commerce menus. It's broad and refreshed continuously, but a store without an online menu won't appear, and the latest crawl may be hours to days old.

Employee-level data is retailer-only. Bridge accounts see sales and inventory for connected stores, but not budtender-level breakdowns.

No cross-account writes, no PII. Sales data is aggregated. There's no access to individual customers or transactions beyond the aggregate measures documented in the tool references.

Tips for reliable answers

Always name a time window. This is the single biggest accuracy improvement. Without one, sales queries cover all-time history. "Last 30 days", "this month", "Q2", and "2026-06-01 to 2026-06-30" all work.

Watch out for "last month" vs. "the last month". Humans are ambiguous about this; so are AIs. If you mean the calendar month of June, say "June" or "last calendar month". If you mean the trailing 30 days, say that.

Names get resolved, but check the resolution. When you say "eighths" or a rough brand name, the AI looks up the exact values in your data first. If a brand name is ambiguous (two similar names in your catalog), it may pick the more popular one. When precision matters, name the product exactly or ask what it matched.

Revenue measures: know which one you're getting. "Total revenue" is net of discounts; "gross sales" is before discounts. If the distinction matters for your question, say which one you want.

Growth figures are fractions in benchmarks. Benchmark growth values come back as decimals (0.0518 means +5.18%). The AI normally converts these for you, but if you see a suspiciously small "growth" number, that's what happened.

Long conversations can drift. If you've been going back and forth for a while and answers start referencing stale filters, start a fresh chat and restate the question.

FAQ

Is my data safe? What can the AI provider see?

You authenticate with your own Headset login through OAuth, and every query runs under your account's permissions: you can only ever see stores and data your Headset user can see. The AI assistant (Claude or ChatGPT) processes query results in order to answer you, subject to that provider's data policies, so treat it like any other third-party tool your team approves. The Headset MCP server itself stores no conversation content.

Why don't I see all the tools mentioned in the reference articles?

The server only lists tools your subscription includes. Retailer subscribers see the retailer set, Bridge subscribers see the bridge set, and the two menu-intelligence tools additionally require the Competitive Intelligence add-on.

I got a "subscription required" message. Is something broken?

No. You asked a question that needs an add-on your account doesn't have (most commonly Competitive Intelligence for competitor menu questions). The message explains what the add-on unlocks; reach out to [email protected] if you'd like it.

Can the AI change anything in my Headset account?

No. Every tool is read-only and declared as such to the AI client. There is no tool that writes, updates, or deletes anything.

How fresh is the data?

Sales and inventory queries hit the same data pipeline as Headset's apps, so freshness matches what you see in Headset for your POS connection. Benchmarks are monthly. Competitive menu data reflects the most recent crawl of each store's public menu.

Does it work on mobile?

Yes, once the connector is set up. Remote connectors run through the AI provider's cloud, so a connector you configured on the web or desktop is available in that provider's mobile app too (subject to the provider's own connector support on mobile).

Can my whole team use it?

Yes. On Claude Team/Enterprise an admin adds the connector once and each member connects with their own Headset login. Everyone's access mirrors their own Headset permissions.

Why did the same question give slightly different numbers than my dashboard?

Usually one of three things: a different time window (trailing 30 days vs. calendar month), net vs. gross revenue, or a filter the AI applied that the dashboard doesn't (or vice versa). Ask the AI what it filtered on, and compare with the dashboard's settings. If numbers still don't reconcile, contact support with both screenshots.

Something's not working. What should I include in a support request?

Which AI client you're using (Claude or ChatGPT) and your plan, the prompt you asked, what happened (error text or screenshot), and roughly when it happened. That's usually enough for us to trace it.