MCP Reference

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.

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

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

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

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.

START

USE CASES

SET UP

OPERATE

RECOVER

AGENT ACCESS

REFERENCE