> ## Documentation Index
> Fetch the complete documentation index at: https://storekit.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Your AI Agent

> Fix common problems connecting Claude, ChatGPT or another MCP client to storekit: sign-in failures, unauthorised errors, wrong store and timeouts.

Work through the section that matches what you see. If none of them fit, email [mcp@storekit.com](mailto:mcp@storekit.com) with the name of your assistant, the question you asked and the time you asked it — every request carries an ID that we can look up.

## Connecting

<AccordionGroup>
  <Accordion title="The sign-in page says 'This connection link is invalid or has expired'">
    The sign-in link your assistant opened was used already or took too long. Go back to the assistant and start the connection again; do not reload the storekit tab.
  </Accordion>

  <Accordion title="The sign-in page says 'Couldn't complete the connection'">
    storekit could not finish the hand-off to your assistant. Try once more from the assistant. If it fails a second time, your account is probably not yet enabled for the beta — [request access](https://t09czsyu90l.typeform.com/to/G6rIJWNv), or email [mcp@storekit.com](mailto:mcp@storekit.com) quoting the email you signed in with.
  </Accordion>

  <Accordion title="My client says 401 or Unauthorised">
    * Your sign-in has expired or was cleared. Use the assistant's reconnect option (see your [connect guide](/docs/guides/ai/overview#connect-your-assistant)).
    * Some clients need you to switch the connector on inside the chat as well as adding it. Check the chat's tools menu.
  </Accordion>

  <Accordion title="My client cannot add the server or says it does not support this transport">
    storekit uses MCP Streamable HTTP. A client that supports only stdio or SSE cannot connect directly; see [Connect Other Clients](/docs/guides/ai/connect/other-clients) for the options.
  </Accordion>
</AccordionGroup>

## Answers Look Wrong

<AccordionGroup>
  <Accordion title="It reports on the wrong store, or on every store">
    Name the store in your question. When you do not, order lists cover the whole account and totals are summed across it. If the account has stores in different currencies, account-wide totals are refused and the assistant asks you to pick one.
  </Accordion>

  <Accordion title="Totals are about a hundred times too big">
    storekit returns money in minor units (pence, cents) and the assistant has shown the raw number. Tell it "amounts are in pence, show them in pounds". This is a presentation slip by the assistant, not a data error; the currency is included with every figure.
  </Accordion>

  <Accordion title="Yesterday's numbers do not match the dashboard">
    Check three things:

    1. **Which clock.** A single store is reported in its local time. Account-wide questions use UTC unless you name a timezone.
    2. **Which date.** Orders are listed by when they are due (their slot), not when they were placed, unless you ask for "placed" or "created". Sales stats and top products always use when the order was placed. Refunds use the refund date unless you ask by order date.
    3. **Which orders.** Totals exclude rejected and cancelled orders and are gross of refunds.

    The [Reports](/docs/guides/reports/overview) pages describe how the dashboard counts, so you can line the two up.
  </Accordion>

  <Accordion title="It says the period is too long">
    One question can cover at most 90 days. Ask in two parts, or ask for a monthly breakdown.
  </Accordion>

  <Accordion title="It says the total is an estimate, or the count changed between pages">
    Large order lists report an estimated total for speed; the individual pages are exact. Order lists are also live, so an order that arrives while the assistant is paging can shift the results. Ask again with a narrower period if you need a firm count.
  </Accordion>

  <Accordion title="A snooze report says events were truncated">
    Events per item are capped at 100 in one answer. The summary and totals are still complete; only the individual on/off events are cut. Ask for a shorter period to see them all.
  </Accordion>

  <Accordion title="Top products show a price that is not what we sold at">
    Prices in the top-products answer are current menu prices, for reference. Quantities are historical; prices are not.
  </Accordion>
</AccordionGroup>

## Slow or Failing Requests

<AccordionGroup>
  <Accordion title="It timed out">
    Each request has 30 seconds. Long periods on busy stores can exceed that — ask for a shorter period or one store at a time. If a **write** timed out, check the dashboard before asking again: the discount code or payment link may already have been created.
  </Accordion>

  <Accordion title="Too many requests">
    Requests are rate-limited per user. Wait a minute and try again. If an automated setup hits this regularly, space out its calls.
  </Accordion>

  <Accordion title="The assistant created something twice">
    This happens when the assistant retries a write after a timeout or a dropped connection. Archive the duplicate discount code or deactivate the duplicate payment link in the dashboard, and keep write approvals set to per call rather than "always allow".
  </Accordion>
</AccordionGroup>

## Still Stuck

<CardGroup cols={2}>
  <Card title="Email mcp@storekit.com" icon="envelope" href="mailto:mcp@storekit.com">
    Tell us the assistant, the question and the time.
  </Card>

  <Card title="Merchant MCP reference" icon="code" href="/docs/developers/mcp/overview">
    For developers: the protocol, tools and error codes.
  </Card>
</CardGroup>


## Related topics

- [Connect Your AI Agent](/docs/guides/ai/overview.md)
- [Connect Claude](/docs/guides/ai/connect/claude.md)
- [Connect ChatGPT](/docs/guides/ai/connect/chatgpt.md)
- [Connect Claude Code](/docs/guides/ai/connect/claude-code.md)
- [Connect Other Clients](/docs/guides/ai/connect/other-clients.md)