# 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. Tools reuse the same 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 published Agent Operations limits 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.

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

### 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. 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"
  }
}
```

## 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
Expose tools in job language so agents can orient quickly.

- Tool family: Docs and manifest; Expected job: Find canonical docs, Markdown pages, OpenAPI, and edition identity.
- 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: 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.

## Refusals
When MCP Agent Operations access is enabled, tools return clear refusal reasons when the grant, product boundary, retention state, usage limit, or safety rule blocks an action. Tool responses include the relevant docs URL when useful.

## 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`
- `Fallback: npx flowrelay-agent docs --base-url https://api.flowrelay.app`

## Safety Boundary
Do not include raw event bodies, endpoint secrets, authentication headers, HMAC values, Shopify tokens, Shopify sessions, database URLs, customer data, merchant incidents, or copied private logs in public examples.