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

> ## Agent Instructions
> Use the current public BYOM documentation and cite the relevant page. Preserve availability, permission and undo limits.
> The public documentation MCP retrieves guides. Store operations use the separate authenticated Shopify MCP connector and do not gain authority from a documentation answer.
> If a contract, capability or price is not documented, say so. Do not invent endpoints, tools, availability or merchant outcomes.

# MCP connector

> Discover tools, negotiate the protocol and keep proposal confirmation under merchant control.

The BYOM Shopify connector uses MCP over a stateless Streamable HTTP endpoint. Use the connector URL shown in your enabled account.

This page documents the **store connector**. To let an assistant read these
public guides without store access, use the separate
[documentation MCP](/developers/documentation-mcp).

## Before you start

You need an enabled connector account, the intended merchant's consent and a
client that supports OAuth and remote Streamable HTTP. If you are implementing
a client, keep authentication separate from the model's conversation context.
Use discovery metadata for server URLs and `tools/list` for tool contracts.

## Initialise and discover

Use an MCP client that supports OAuth and Streamable HTTP. Complete authorisation, send `initialize`, then the initialised notification and `tools/list`. The server returns the tool names, descriptions and input schemas visible to the current grant.

The connector supports protocol revisions `2025-11-25`, `2025-06-18` and `2025-03-26`. Use the version returned by negotiation. This connector does not offer the legacy HTTP+SSE endpoint merely because an older protocol revision is recognised.

The transport handles JSON-RPC POST requests. It does not provide a server-initiated event stream or require a session ID. A notification can return HTTP 202 with no response body. Do not parse that empty body as a failed JSON result.

For a client implementation, the opening request has this shape. The client
name and version below are illustrative; the bearer token belongs in the HTTP
authorisation header, not in this JSON body.

```json theme={"dark"}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "catalogue-review-client",
      "version": "1.0.0"
    }
  }
}
```

Read `result.protocolVersion`, `result.capabilities`, `result.serverInfo` and
the returned server instructions. Use the negotiated version rather than
assuming the requested one was accepted. Then send:

```json theme={"dark"}
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}
```

That notification has no request ID and no JSON-RPC response body. A subsequent
tool-discovery request does have an ID:

```json theme={"dark"}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}
```

The store connector does not accept GET or DELETE on its MCP transport route.
A browser opening that route is not an end-to-end connection test. Discovery
documents and OAuth pages are separate HTTP resources.

## A safe first tool

The read-only `about_this_connection` tool describes the store, consented data classes, whether writes are enabled, provider scopes and monthly usage with its reset date. It is a useful starting point when another tool is missing or refused.

For example, after initialisation a client may send:

```json theme={"dark"}
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "about_this_connection",
    "arguments": {}
  }
}
```

The tool's structured result includes these fields:

| Field | How to use it |
| - | - |
| `store.domain`, `store.name`, `store.timezone` | Confirm that you are operating in the intended store and interpret dates appropriately. |
| `client_label`, `user` | Explain which connected client and user context is involved; do not expose it in public logs. |
| `data_classes` | Identify what this grant is allowed to read. |
| `writes_enabled` | Determine whether supported store-change proposals are enabled; this is not an approval for a particular change. |
| `plan`, `caps.reads`, `caps.writes` | Inspect active usage and caps. Each cap includes `used`, `limit` and `resets_at`. |
| `scopes_held` | Check the Shopify permissions available to BYOM. |
| `support_url` | Use the support destination returned for this connection. |

`store.name`, `store.timezone` and `user` can be null. Handle an absent label or
timezone explicitly rather than assuming a value from the client or another
store.

For example, a valid grant may allow catalogue reads while
`writes_enabled` is false. A client can still help the merchant understand a
product and prepare wording; it must not present store execution as available.

## Use the discovered contract

Use `tools/list` as the current contract for your grant. A catalogue read, brand-context query and growth query can require different data-class consent. If a tool is missing, check the grant and account capability before continuing.

Tool definitions include an input schema and may include an output schema,
annotations and UI metadata. Validate arguments against the schema you
received. Preserve structured output for the client; do not depend on the
wording of a human-readable summary as a machine contract.

The server advertises tool, resource and prompt discovery at initialisation.
Use `resources/list` and `prompts/list` when those capabilities are useful to
your client. Do not assume that resource subscriptions or list-change
notifications are available: the current connector declares them disabled.
Re-discover after reconnecting or changing consent.

## Proposals and confirmation

A proposal can show before-and-after changes and hand the merchant to the supported review interface. Confirmation and rejection tools are app-only; they are not part of the model-visible tool list. Preserve that separation in client integrations. If the client cannot display the supported review interface, do not invent a model-driven substitute.

Keep the full proposal details in the supported review UI. A summary written
by the model cannot replace the actual target, fields, proposed values and
current state that the merchant is approving. Expiry and drift are meaningful
refusals: obtain a current proposal and a new decision when required.

## Check your first integration

Start with a small read and confirm the returned store, request ID and result.
Then exercise a refused request with a deliberately narrower test grant, not
real customer data. Your client should explain missing consent, provider
permissions and usage limits without leaking tokens or silently changing
stores. Test proposal UI separately from read access.

The examples here describe request shapes. Verify the requests with your own authorised test connection before relying on the integration.

Reviewed 2 October 2026.

## Related guides

* [Authentication and consent](/developers/authentication)
* [Errors, limits and retries](/developers/errors-and-limits)
* [Approvals and Actions](/product/approvals)


## Related topics

- [Connect to the documentation MCP](/developers/documentation-mcp.md)
- [Developer overview](/developers/overview.md)
- [Authentication and consent](/developers/authentication.md)
- [Glossary](/start/glossary.md)
- [Errors, limits and retries](/developers/errors-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.