# MCP Reference

Canonical: https://docs.flowrelay.app/reference/mcp/
Markdown: https://docs.flowrelay.app/reference/mcp.md

MCP Agent Operations access over the same scoped Agent Operations contract when enabled.

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

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

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

```sh
Authorization: Bearer $FLOWRELAY_AGENT_TOKEN
```

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

```sh
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.

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

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

```sh
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.

```json
{
  "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: Docs and manifest; Expected job: Find canonical docs, Markdown pages, OpenAPI, and edition identity.
- Tool family: Public status link; Expected job: Read aggregate FlowRelay service status from https://api.flowrelay.app/status.json without tenant-specific access or incident-publishing authority.
- Tool family: Endpoint setup and mapping; Expected job: Use OpenAPI plus the trigger mapping reference before creating or editing endpoints.
- Tool family: Mission playbooks; Expected job: Map the operator's goal to context reads, safe actions, and escalation boundaries.
- Tool family: Agent setup and endpoint swap guides; Expected job: 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.
- Tool family: Availability and refusals; Expected job: Explain whether a capability is allowed by scope, usage, target state, safety, and product boundary.
- Tool family: Event investigation; Expected job: Read event history, receipts, lifecycle state, retention, and replay availability.
- Tool family: Recovery previews; Expected job: Preview replay, diagnostics share, or other approved action previews.
- Tool family: Support and product-demand requests; Expected job: 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.

## Example Surface
- `Endpoint: https://api.flowrelay.app/agent/v1/mcp`
- `Authorization: Bearer $FLOWRELAY_AGENT_TOKEN`
- `Public status JSON: https://api.flowrelay.app/status.json`
- `Fallback: npx flowrelay-agent docs --base-url https://api.flowrelay.app`

## Safety Boundary
Do not share endpoint secrets, authentication headers, HMAC values, tokens, raw event bodies, customer records, Shopify sessions, store passwords, or database URLs in public examples.