Confirmed actionsCopy Anchor Link

A mutating tool never changes anything on its first call. FloPay checks the request, returns a preview of exactly what would happen, and waits. The action runs only when your client sends back the operator's explicit acceptance, and FloPay checks everything again before it writes.

Each tool's class, risk, and retry policy are in the Tool reference. Reviewed high- and critical-risk actions use the same preview and explicit confirmation flow, with stronger operation-specific warnings and the restricted rate-limit tier. Unavailable operations lists reviewed exclusions and the surfaces outside the merchant MCP boundary.

Which clients see mutating toolsCopy Anchor Link

A mutating tool appears in tools/list and search results, and can be called, only when all of these hold for the request:

• The access token carries the mcp:write scope.
• The operator's current merchant role appears in the tool's Roles policy. Some actions allow member; others require admin or owner.
• The request declares form elicitation in io.modelcontextprotocol/clientCapabilities: "elicitation": { "form": {} }, or an elicitation object that lists no mode. A client that declares only URL elicitation stays read-only.

Otherwise the tool is hidden, and calling it returns JSON-RPC error -32602 with Unknown or unavailable tool. Declare the same capabilities on the preview call and the confirmation call.

PreviewCopy Anchor Link

Call the tool with its arguments, exactly as you call a read-only tool, using the headers from Connect any MCP client with Mcp-Name: ProductBrand_create:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "ProductBrand_create",
    "arguments": { "code": "summer-range", "name": "Summer range" },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": { "elicitation": { "form": {} } }
    }
  }
}

FloPay runs the same validation and permission checks the action itself would run, then stops before writing, so the preview does not change anything. FloPay MCP answers with an input_required result that holds a confirmation form:

{
  "jsonrpc": "2.0",
  "id": 10,
  "result": {
    "inputRequests": {
      "flopay/confirmation": {
        "method": "elicitation/create",
        "params": {
          "mode": "form",
          "message": "Review the authoritative FloPay preview and explicitly accept to execute: {\"operationId\":\"ProductBrand_create\",\"inputHash\":\"<input hash>\",\"actionPrincipal\":{\"actorId\":\"3c6f1e2a-8b4d-4f7e-9a1c-5d2e8b7f4a3c\",\"authMethod\":\"oauth-bearer\",\"clientApplicationId\":\"7d0c6c2e-4b1f-4f7a-9c1e-2f8b7a1d0e5c\",\"merchantId\":\"0f8e4c1a-6d2b-4e7f-8a9c-3b5d7e1f2a4c\",\"role\":\"admin\",\"scopes\":[\"mcp:read\",\"mcp:write\"]},\"authorization\":{\"role\":\"admin\",\"scopes\":[\"mcp:read\",\"mcp:write\"],\"permissions\":{\"roles\":[\"owner\",\"admin\"],\"scopes\":[\"mcp:write\"]},\"policyHash\":\"<policy hash>\"},\"targets\":[{\"type\":\"product-brand-code\",\"id\":\"summer-range\",\"version\":\"absent\"}],\"effects\":[{\"type\":\"create-product-brand\",\"targetId\":\"summer-range\",\"details\":{\"before\":null,\"after\":{\"code\":\"summer-range\",\"name\":\"Summer range\",\"description\":null}}}],\"warnings\":[\"Product brand id and timestamps are assigned only when the confirmed action executes.\"],\"normalizedProposedValues\":{\"code\":\"summer-range\",\"name\":\"Summer range\",\"description\":null},\"validationOutcome\":{\"valid\":true,\"checks\":[\"dto\",\"product-brand-code-available\"]},\"expectedResult\":{\"responseType\":\"ProductBrandDto\",\"projected\":{\"code\":\"summer-range\",\"name\":\"Summer range\",\"description\":null},\"serverAssignedFields\":[\"id\",\"createdAt\",\"updatedAt\"]},\"expiresAt\":\"2026-09-14T15:05:00.000Z\"}",
          "requestedSchema": {
            "type": "object",
            "properties": {
              "idempotencyKey": {
                "type": "string",
                "title": "Idempotency key",
                "description": "A client-generated retry identity for this action."
              }
            },
            "required": ["idempotencyKey"]
          }
        }
      }
    },
    "requestState": "<confirmation state>",
    "_meta": {
      "flopay/contractRevision": "<contract revision>",
      "flopay/httpStatus": 201,
      "flopay/confirmationPhase": "preview",
      "io.modelcontextprotocol/serverInfo": { "name": "flopay-mcp", "version": "<server version>" }
    },
    "resultType": "input_required"
  }
}

The form message carries the preview from the FloPay API. Show the operator what it says before asking for a decision:

requestState is an opaque confirmation token. Keep it as it is and never show it to the model or the operator. If FloPay rejects the preview, because the arguments are invalid or the operator can no longer run the action, FloPay MCP answers JSON-RPC error -32603 with Backend action preview is invalid. Check the arguments against the tool's entry in the Tool reference before trying again.

Confirm or declineCopy Anchor Link

To run the action, call the same tool again with the same name and arguments, echo requestState, and send the operator's decision in inputResponses:

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "ProductBrand_create",
    "arguments": { "code": "summer-range", "name": "Summer range" },
    "requestState": "<confirmation state>",
    "inputResponses": {
      "flopay/confirmation": {
        "action": "accept",
        "content": { "idempotencyKey": "5b7e2c90-3d4f-4a8b-9c1d-6e2f7a8b9c0d" }
      }
    },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": { "elicitation": { "form": {} } }
    }
  }
}

Every confirmed action requires an idempotency key that your client generates once for this intended action, such as a UUID. The result is the FloPay API response for the action, in the shape the tool's entry in the reference documents.

If the operator declines or dismisses the form, send decline or cancel as the action instead. FloPay MCP answers FloPay action was not executed. and does not contact the FloPay API.

A confirmation:

• expires five minutes after the preview,
• works for one execution only,
• is bound to the operator, the merchant, the client application, the tool, the exact arguments, the operator's role and scopes, and the version of every record the preview targeted.

If anything the confirmation is bound to changes after the preview, for example someone else edits the same record, FloPay refuses to run the action. Call the tool again for a fresh preview.

An action that reaches the FloPay API but does not complete returns a tool result with isError: true, the status in flopay/httpStatus, and the API response in structuredContent:

The responses about unclear outcomes also carry a reconciliation field with the same instruction: do not retry automatically, and check the record first.

Retry an actionCopy Anchor Link

Start with the tool's Retry policy in the Tool reference. Do not retry automatically after a timeout, lost connection, or ambiguous result. First read the canonical target record and use the response's reconciliation guidance.

• same-idempotency-key. An exact replay uses the same confirmation, arguments, and idempotency key. If the first attempt completed, FloPay returns its original result instead of running the action twice. FloPay keeps that result for at least 24 hours. If FloPay says the outcome is not authoritative, reconcile instead of replaying again.
• manual-reconciliation. Never resubmit automatically after execution may have started. Read the target through its canonical read tool, then let the operator decide whether to request a new preview.
• A confirmed failure before any write. When FloPay can prove no write began, it returns that failure normally. Correct the input or permissions, then start again with a new preview and a new key.

An idempotency key can be up to 200 characters. Never reuse a key for a different action: FloPay refuses it with 409.

The following tools declare manual-reconciliation because their outcome cannot be safely repeated once FloPay starts writing. A failure after writing starts answers 503 with The MCP action outcome is ambiguous., and you must read the record before deciding anything:

• Checkouts: Session_create and Session_createSetup. Setup returns one-time card capture credentials. They are issued once, and a repeated call returns only a reference to the session.
• Settings: ChargebackSettings_createDescriptor, GatewaySettings_activate, GatewaySettings_create, GatewaySettings_deactivate, GatewaySettings_update, and PreDisputeAlertSettings_enrollDescriptor.
• Subscriptions: SubscriptionChange_change, SubscriptionChange_withdrawChange, SubscriptionControl_cancel, SubscriptionControl_extend, SubscriptionControl_pause, SubscriptionControl_reactivate, SubscriptionControl_resume, and SubscriptionCreate_create.
• Transactions: CreatePayment_create, Payments_cancelAuthorization, Payments_captureAuthorization, and Payments_refund.
• Users and payment methods: PaymentMethods_delete, User_merge, and User_updateUser. Read the customer or payment-method state to see whether the change was applied. After an unclear User_merge, read both customers before deciding anything: a merge that committed cannot be undone.
• Webhooks: ClientWebhookEvent_resend and ClientWebhookEvent_resendMany.

Tools with the same-idempotency-key policy can be retried with the same idempotency key as described above. Do not retry automatically when FloPay says a result is not yet authoritative.