> ## 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.

# Merchant MCP Overview

> Remote, account-scoped Model Context Protocol server giving an AI client read access to storekit orders, menus, stats, refunds and bills, plus two writes.

**Who this is for:** a developer wiring an AI client or agent to a merchant's own storekit account. For the customer-side surfaces — an agent reading a public menu and building a basket — see [Ordering Agents](/docs/developers/agents/ordering/overview). For the non-technical setup guides, see [Connect Your AI Agent](/docs/guides/ai/overview).

<Note>
  **Beta feature** - The merchant MCP is in beta and accounts are enabled from a waitlist. [Request access](https://t09czsyu90l.typeform.com/to/G6rIJWNv), or email [mcp@storekit.com](mailto:mcp@storekit.com).
</Note>

## Endpoint

|           |                                                                                                                                     |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| URL       | `https://mcp.storekit.com/mcp`                                                                                                      |
| Transport | MCP [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports), JSON responses (no SSE streaming) |
| Methods   | `POST` for JSON-RPC messages; `GET` and `DELETE` per the transport spec                                                             |
| Session   | Stateless. `initialize` returns an `Mcp-Session-Id` header, but requests are not validated against it                               |
| Auth      | OAuth 2.1 bearer token — see [Authentication](/docs/developers/mcp/authentication)                                                       |
| Discovery | `GET /.well-known/oauth-protected-resource`                                                                                         |

Every request creates a fresh MCP server bound to the authenticated account, handles one message and closes. Nothing is remembered between calls; a conversation carries venue IDs and order IDs itself.

## Tools

Eighteen tools, all scoped to the authenticated account. Sixteen are read-only (`readOnlyHint: true`); `create-discount-code` and `create-payment-link` are writes. The full input reference is on [Tools](/docs/developers/mcp/tools).

| Domain        | Tools                                                                                  |
| ------------- | -------------------------------------------------------------------------------------- |
| Venues        | `list-venues`, `get-venue`                                                             |
| Orders        | `list-orders`, `get-order`, `get-order-events`                                         |
| Menus         | `list-menus`, `get-menu`                                                               |
| Snoozing      | `get-snooze-report`                                                                    |
| Stats         | `get-order-stats`, `list-top-products`                                                 |
| Discounts     | `list-discount-codes`, `create-discount-code`                                          |
| Refunds       | `list-refunds`                                                                         |
| Pay at table  | `list-bills`                                                                           |
| Payment links | `list-payment-links`, `get-payment-link`, `create-payment-link`, `get-payment-link-qr` |

There are no tools that mutate orders, menus, venues, users or settings.

## Contract in Brief

* Every success is a `{ data, meta }` envelope, returned both as `structuredContent` and as JSON in the first text block. Every tool publishes an `outputSchema` for it. See [Response Format](/docs/developers/mcp/response-format).
* Errors are text-only `isError: true` results carrying an `{ error }` envelope with a stable `code`. See [Errors](/docs/developers/mcp/errors).
* Money is in **minor units** with an explicit currency code. Dates are strict ISO. Venue-scoped queries default to the venue's timezone, account-wide queries to UTC.
* Pagination starts at page 1, is capped at 100 rows, and reports `hasMore`/`nextPage` from a one-row lookahead rather than from totals.

## Limits

| Limit                  | Value                                                                 |
| ---------------------- | --------------------------------------------------------------------- |
| Rate                   | 60 requests per minute per user; `429` with `Retry-After` beyond that |
| Tool timeout           | 30 seconds; a timed-out write may still have completed                |
| Page size              | 100 rows (25 for `list-top-products`)                                 |
| Date range             | 90 local calendar dates, inclusive                                    |
| Snooze events per item | 100, flagged with `eventsTruncated`                                   |

## Reference

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/docs/developers/mcp/authentication">
    OAuth discovery and sign-in, how the account is chosen.
  </Card>

  <Card title="Tools" icon="wrench" href="/docs/developers/mcp/tools">
    Every tool with its inputs, defaults and date basis.
  </Card>

  <Card title="Response Format" icon="brackets-curly" href="/docs/developers/mcp/response-format">
    The envelope, pagination, dates, timezones and money.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/docs/developers/mcp/errors">
    Error codes, retry rules and the shapes clients must handle.
  </Card>
</CardGroup>


## Related topics

- [Developer Introduction](/docs/developers/introduction.md)
- [Ordering Agents Overview](/docs/developers/agents/ordering/overview.md)
- [MCP Endpoint](/docs/developers/agents/ordering/mcp-endpoint.md)
- [First Delivery dispatch aggregation](/docs/guides/integrations/delivery/first-delivery.md)
- [Webhooks Overview](/docs/developers/webhooks/overview.md)