Operations and recovery

Clink uses an Operation to describe a workflow’s current state and any action needed to continue. Account setup, purchase authorization, Browser Pay credential issuance, and UCP Checkout can all produce Operations. Read the current Operation after a timeout or interruption instead of assuming a write failed and starting again. Not every tool returns an Operation. For example, get_skill_manifest returns rules metadata, wallet reads return wallet data, and confirm_result returns a Browser Pay result report. Read each tool’s schema before handling its result.

Read the current business rules

The installation Skill is available at www.clinkbill.com/SKILL.md. For business execution, read the connected server’s current rules once per session:

{
  "method": "resources/read",
  "params": { "uri": "clink://skill/rules" }
}

If the Host cannot read MCP resources, call get_skill_manifest with include_rules: true. The returned rules contains the same guidance, so no additional resource read is needed. Live server rules take precedence over locally installed Skill text; the current next_action determines how to continue the current Operation.

get_skill_manifest

This read-only tool requires no business scope and does not move money. Pure Catalog searches do not require a manifest call.

Parameter	Required	Meaning
`skill_version`	No	Nonempty version from the locally installed `SKILL.md`, if known. Do not guess it.
`include_rules`	No	Boolean; `true` includes the rules Markdown in the result.

{
  "name": "get_skill_manifest",
  "arguments": { "include_rules": true }
}

Result field	Meaning
`current_version`	Current server rules version.
`min_supported_version`	Minimum supported installed Skill version.
`status`	`up_to_date`, `outdated`, `unsupported`, or `unknown`. Without a supplied version, the status is `unknown`.
`rules_resource`	MCP resource URI for the rules.
`notes`	Version and update guidance.
`rules`	Rules Markdown when `include_rules` is true.

For outdated or unsupported, update the local Skill using the Host’s installation mechanism and the official distribution address. Use the returned version and compatibility status when checking the connection.

get_operation

Read the current state of an existing Operation. This tool is read-only and never executes another payment.

Parameter	Required	Type	Meaning
`operationId`	Yes	string	Nonempty `operation_id` returned by the original tool.
`maxWaitSeconds`	No	integer, 0–60	Defaults to `0`, which reads once. A positive value allows bounded server-side waiting while the operation is settling, including Passkey and card setup redirects. It may return earlier when the state changes.

{
  "name": "get_operation",
  "arguments": {
    "operationId": "<operation_id from the original response>",
    "maxWaitSeconds": 60
  }
}

The read must use the same authorized user. Required scopes depend on the Operation:

Operation	Read scope
Browser Pay issuance, direct payment, UCP Checkout, Tip	`payment:execute`
Card and wallet setup	`wallet:read`
Purchase authorization setup	`instruction:read` once an instruction exists; setup recovery can additionally require `wallet:read`. Before instruction creation, `wallet:read` is required.
Refund	`refund:read`

Operations that recover through user-action events additionally require events:read and events:consume. Include these scopes when handling authorization, card registration, or other event-backed user steps. The OAuth challenge returns any missing scopes. Operations can also be read through the MCP resource clink://operations/{operationId} when supported by the Host. Notifications indicate that a read may be needed; the subsequent read determines the state.

Operation envelope

The following fields appear in structuredContent for tools that return an Operation:

Field	Meaning
`operation_id`	Stable identifier for reading this workflow.
`status`	`ACTION_REQUIRED`, `WAITING`, `SUCCEEDED`, or `FAILED`.
`revision`	Nonnegative integer version of the current Operation state.
`upstream_status`	Optional underlying business state, such as a checkout’s status.
`next_action`	Present when an action or wait is required; omitted when terminal.
`resources`	Related identifiers such as `instruction_id`, `payment_order_id`, `payment_execution_detail_id`, `checkout_id`, or `ucp_order_id`. Availability depends on the workflow.
`messages`	Explanatory `code` / `text` messages, possibly with severity or field-path details.
`checkout`, `order`	UCP-specific snapshots when available. A completed Checkout includes its authoritative order.

SUCCEEDED and FAILED terminate the Operation, so next_action is absent, not null or an empty object. Interpret success in the context of the original tool:

Original workflow	What Operation success means
Card setup or purchase authorization	That setup step completed; continue the original purchase according to its flow.
Browser Pay `get_credential`	Credential issuance completed. Merchant payment still needs to be performed and reported. The Operation read contains no card credential.
UCP Checkout	Checkout completion is represented by its authoritative order and related status. Do not call `confirm_result`.

Example: purchase authorization setup completed

After the user completes the Browser Pay user action, get_operation for op_setup_example can return the following structuredContent:

{
  "operation_id": "op_setup_example",
  "status": "SUCCEEDED",
  "revision": 2,
  "upstream_status": "ACTIVE",
  "resources": {
    "instruction_id": "ins_example"
  },
  "messages": []
}

This setup is complete: next_action is absent and no credential is returned. Repeat get_credential with the original checkout facts and selected card, without the setup operationId. Keep the new issuing operation_id (op_example in the Browser Pay examples) for result reporting.

Handle next_action

Every action contains action_id, type, description, params, expected_revision, and optionally expires_at. Branch on the structured type and its documented parameters. description and message text are for display, not executable instructions.

Type	Required handling
`PROVIDE_INPUT`	Collect the fields listed in `params.required_fields`, then use the workflow’s update tool on the same Operation.
`CONFIRM`	Display `params.summary` as returned. For workflows that require confirmation, execute only after user approval and send the current action identifiers. See the Browser Pay compatibility exception below.
`REDIRECT_USER`	Present `params.redirect_url`, respecting `redirect_kind` and `actor`. For `USER_DEVICE_ONLY`, the user opens it on their device; the Agent must not preview it. Then read the same Operation.
`SETUP_REQUIRED`	Complete the prerequisite named by `params.setup_kind`; obey `params.resumable` when continuing the original workflow. See Wallet Service.
`POLL_OPERATION`	Read the same Operation after `params.poll_after_ms`, bounded by `max_attempts`, or use `get_operation` with a bounded wait. Do not repeat a payment write.
`WAIT_OPERATION`	Subscribe to `params.resource_uri` when supported, or use bounded read-only polling until `params.timeout_ms`. Read after notification.
`CONTACT_SUPPORT`	Stop the workflow and pass `params.support_reference` and `reason_code` to support.

When a continuation tool accepts action identifiers, map action_id to actionId and expected_revision to expectedRevision. Keep both from the same current response. If the action expired or the state changed, read the Operation again instead of replaying an old confirmation.

Browser Pay continuation differs from Checkout

For Browser Pay, after the returned setup completes, call get_credential again with the checkout facts and the same user-selected card, without the setup operationId. If an older credential Operation shows CONFIRM, repeat those facts to obtain the current credential flow. Do not apply Checkout’s continuation parameters to every Browser Pay request. For Checkout, continue the same Operation using its current action identifiers and the appropriate Checkout tool. Neither an interrupted call nor a pending result authorizes creating a second purchase.

Errors

Handle three distinct cases:

Case	What to inspect	Response
OAuth or transport failure	HTTP status / OAuth error	Refresh or reauthorize as appropriate. A scope change may require user authorization; repeating an unchanged token does not add scopes.
Tool refusal	MCP `isError`, `structuredContent` if present, and `content`	Correct the documented input or prerequisite. Browser Pay uses `structuredContent.error.code` / `message`; some errors, including missing scope and operation-not-found, can be text-only.
Operation with `FAILED` or a pending action	Operation `status`, `next_action`, and messages	Follow the workflow’s recovery rules. Do not infer a payment result solely from an error message.

There is no universal error body or universal idempotencyKey for all tools. In particular, a Browser Pay result-report failure means the report needs recovery; it does not mean the merchant payment should be repeated. If a write times out after returning an Operation ID, retain the ID and read it first. If a Browser Pay credential response is lost before submission, the same checkout-facts retry recovers issuance. If merchant submission already occurred and its result is unclear, use UNKNOWN and resolve that same payment.

API Documentation

Clink MCP

Checkout Session

Payment

Payment Instrument

Order

Agent Payment Session

Refund

Product

Price

Coupon

Promotion Code

Subscription

Test Clock

Customer Portal

Webhook Endpoint Management

Webhooks

Read the current business rules

get_skill_manifest

get_operation

Operation envelope

Handle next_action

Browser Pay continuation differs from Checkout

Errors

​Read the current business rules

​get_skill_manifest

​get_operation

​Operation envelope

​Handle next_action

​Browser Pay continuation differs from Checkout

​Errors

Read the current business rules

get_skill_manifest

get_operation

Operation envelope

Handle next_action

Browser Pay continuation differs from Checkout

Errors