MCP Reference

Start here #

Confirm what MCP wraps, the usage limits, and the authenticated endpoint.

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

Use MCP #

Search and execute through the scoped contract, with a stable store-profile ritual.

Search and execute #

MCP exposes two contract-level capabilities: OpenAPI search and controlled execute. It does not create one named MCP tool per Agent Operation. Search the generated schema for the route, operation ID, scopes, effect, and request shape, then use controlled execute only for an allowed same-origin /agent/v1/* operation. Public status is an external aggregate JSON link, not an MCP write or publish path. The same bearer token, scopes, effect model, 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_..."
  }
}

Synthetic contract search Search before execute instead of relying on a cached per-operation tool name.

search OpenAPI for operationId=createReplayIntent
inspect route, requiredScopes, effect, requiresConfirmation, request schema, and docsUrl

Synthetic controlled execute Use placeholders and the exact request shape returned by search.

{
  "method": "POST",
  "path": "/agent/v1/events/flr_evt_synthetic/replay-intents",
  "body": {
    "state": "preview",
    "idempotencyKey": "synthetic-replay-preview-001"
  }
}

Synthetic refusal Stop on authority and product-boundary refusals instead of retrying blindly.

{
  "ok": false,
  "code": "agent_scope_missing",
  "message": "The current grant cannot preview replay.",
  "docsUrl": "https://docs.flowrelay.app/agent-access/grants-and-scopes/"
}

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.

Discover the surface #

Inspect the current tool list instead of relying on cached capability names.

Tool discovery #

Discover the generic OpenAPI search and controlled execute capabilities from the connected MCP server. Operation names, routes, scopes, and effects come from the generated schema rather than from a hand-maintained list of named MCP tools.

Capability	Expected job
OpenAPI search	Find the exact route, generated operation ID, scopes, effect, schema, and canonical docs URL.
Controlled execute	Call an allowed same-origin Agent Operations route with the connected grant and preserve its effect, confirmation, redaction, rate-limit, and refusal behavior.

Handle boundaries and failures #

When a request is refused, stop and follow the documented troubleshooting path.

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