MCP connector - BYOM Docs

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.

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.

{
  "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:

{
  "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:

{
  "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:

{
  "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.

​Before you start

​Initialise and discover

​A safe first tool

​Use the discovered contract

​Proposals and confirmation

​Check your first integration

​Related guides