MCP Reference

What MCP wraps #

MCP Agent Operations access runs over Agent Operations, not a separate authority model. Enabling MCP does not grant new authority; tools reuse the same grant token, scopes, refusal behavior, docs pointers, action previews, and audit semantics. If MCP is unavailable, use the Agent Operations API or CLI.

Usage limits #

Use the plan-usage operation before polling, broad reads, or repeated action previews. MCP tools use the same short-window rate limits, fair-use safeguards, and refusal semantics as API and CLI calls.

Endpoint and auth #

There is no separate MCP download. Configure clients that support remote HTTP MCP with the hosted Agent Operations endpoint and the same merchant-authorized Agent Access bearer token. Treat each MCP host entry as one store-scoped profile: keep the token in private host secret configuration and include expected-context headers when the host supports custom headers. Public aggregate service status is available as JSON at https://api.flowrelay.app/status.json; MCP execution remains limited to allowed /agent/v1/* operations and does not create status-publishing or incident-classification authority.

Endpoint Use this as the remote HTTP MCP server URL.

https://api.flowrelay.app/agent/v1/mcp

Authorization Use the same Agent Access grant token used by the API and CLI.

Authorization: Bearer $FLOWRELAY_AGENT_TOKEN

Expected context Use these headers to bind the MCP profile to the intended platform account, store, and install context.

X-FlowRelay-Expected-Platform-Key: shopify_flow
X-FlowRelay-Expected-Platform-Account-Id: flr_pac_...
X-FlowRelay-Expected-Shop-Domain: client-a.myshopify.com
X-FlowRelay-Expected-Installation-Id: flr_st_...

Public status JSON Use this public aggregate status URL outside the MCP execute tool when an agent only needs service-level status.

https://api.flowrelay.app/status.json

Fallback Use the API or CLI if a client cannot load remote HTTP MCP.

npx flowrelay-agent docs --base-url https://api.flowrelay.app

Search and execute #

MCP Agent Operations access exposes contract search and approved execution over the Agent Operations API. Use search to inspect the OpenAPI contract and execute only for allowed /agent/v1/* operations. Public status is intentionally an external aggregate JSON link, not an MCP write or publish path. For endpoint create or edit work, read the trigger variants and event mapping reference before choosing triggerVariant, resourceIdPath, or relatedResourceIdPath. The same bearer token, scopes, action previews, audit, redaction, and refusal rules apply.

Client configuration shape Use equivalent fields for clients that support remote HTTP MCP server configuration.

{
  "url": "https://api.flowrelay.app/agent/v1/mcp",
  "headers": {
    "Authorization": "Bearer $FLOWRELAY_AGENT_TOKEN",
    "X-FlowRelay-Expected-Platform-Key": "shopify_flow",
    "X-FlowRelay-Expected-Platform-Account-Id": "flr_pac_...",
    "X-FlowRelay-Expected-Shop-Domain": "client-a.myshopify.com",
    "X-FlowRelay-Expected-Installation-Id": "flr_st_..."
  }
}

Store profile ritual #

For agency or repeat operator work, create one MCP host entry per store-scoped grant. Before acting, use MCP to read the grant or manifest, confirm the returned store identity matches the host entry, then check plan usage before polling, broad reads, or repeated previews. A wrong store or installation context returns agent_context_mismatch instead of silently acting in the wrong account.

Hosted MCP endpoint #

The hosted endpoint exposes OpenAPI search and controlled execution for Agent Operations routes. Execution is limited to FlowRelay's same-origin API routes and does not provide general outbound network access.

Tool discovery #

Tools are named for the Agent Operations they perform so agents can find the right operation quickly.

Tool family	Expected job
Docs and manifest	Find canonical docs, Markdown pages, OpenAPI, and edition identity.
Public status link	Read aggregate FlowRelay service status from https://api.flowrelay.app/status.json without tenant-specific access or incident-publishing authority.
Endpoint setup and mapping	Use OpenAPI plus the trigger mapping reference before creating or editing endpoints.
Mission playbooks	Map the operator's goal to context reads, safe actions, and escalation boundaries.
Agent setup and endpoint swap guides	Use Set up with an agent for one new endpoint or Endpoint swap plan for one existing sender lane before changing URLs, auth, or traffic.
Availability and refusals	Explain whether a capability is allowed by scope, usage, target state, safety, and product boundary.
Event investigation	Read event history, receipts, lifecycle state, retention, and replay availability.
Recovery previews	Preview replay, diagnostics share, or other approved action previews.
Support and product-demand requests	Choose support, expansion, or feature-request lanes and submit only in-bounds, non-secret, non-commitment records.

Refusals #

When MCP Agent Operations access is enabled, tools return a machine-readable refusal reason when the grant, product boundary, retention state, usage limit, or safety rule blocks an action. Refusal responses include the relevant docs URL so the agent can correct course instead of retrying blindly.

Troubleshooting #

When a tool cannot act, the agent reads the linked docs page, checks /agent/v1/manifest, inspects OpenAPI, then escalates to a human if the action remains outside authority.

START

USE CASES

SET UP

OPERATE

RECOVER

AGENT ACCESS

REFERENCE