# MCP Reference

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

MCP endpoint over the same scoped Agent Operations contract.

## What MCP wraps
The MCP surface runs over Agent Operations, not a separate authority model. Tools reuse the same scopes, refusal behavior, docs pointers, action intents, and audit semantics.

## 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: 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 governed action intents.

## Refusals
MCP 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
- `GET /agent/v1/manifest`
- `POST /agent/v1/mcp`
- `Tool calls reuse Agent Operations scopes`

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