> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operations and recovery

> Read current MCP rules, handle next_action, and resume an existing operation safely.

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](https://www.clinkbill.com/SKILL.md). For business execution, read the connected server's current rules once per session:

```json theme={null}
{
  "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. |

```json theme={null}
{
  "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. |

```json theme={null}
{
  "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`. |

<Accordion title="Example: purchase authorization setup completed">
  After the user completes the [Browser Pay user action](/api-reference/mcp/browser_pay#get_credential), `get_operation` for `op_setup_example` can return the following `structuredContent`:

  ```json theme={null}
  {
    "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.
</Accordion>

## 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](/guides/agent/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](/api-reference/mcp/browser_pay#continuation-and-retries) recovers issuance. If merchant submission already occurred and its result is unclear, use `UNKNOWN` and resolve that same payment.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.