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

# MCP tools reference

> Every action and parameter for the 19 ovra_* tools.

All 19 tools use an `action` parameter to select the operation. Required parameters per action are enforced via JSON Schema `if/then`.

## Agent tools (9)

### `ovra_pay`

Single entry-point for the full payment flow. Handles intent + policy + credential.

| Action       | Required                                   | Description                            |
| ------------ | ------------------------------------------ | -------------------------------------- |
| `checkout`   | `agentId`, `purpose`, `amount`, `merchant` | Full payment flow in one call          |
| `status`     | `intentId`                                 | Check payment status                   |
| `handle_402` | `agentId`, `url`, `merchant`, `amount`     | Handle HTTP 402 challenges             |
| `discover`   | `agentId`                                  | Show available spend limits and policy |

### `ovra_intent`

Declare and manage payment intents.

| Action    | Required                                          | Description                       |
| --------- | ------------------------------------------------- | --------------------------------- |
| `declare` | `agentId`, `purpose`                              | Create intent — policy check runs |
| `get`     | `intentId`                                        | Fetch detail                      |
| `cancel`  | `intentId`                                        | Cancel an unfilled intent         |
| `verify`  | `intentId`, `actualAmountEuros`, `actualMerchant` | Post-settlement verification      |

### `ovra_credential`

Issue scoped payment credentials. Agent never sees the underlying card.

| Action   | Required                    | Description                        |
| -------- | --------------------------- | ---------------------------------- |
| `obtain` | `intentId`                  | Grant + issue + redeem in one call |
| `grant`  | `intentId`                  | Grant only                         |
| `issue`  | `grantId`                   | Issue from grant                   |
| `redeem` | `credentialId`              | Get DPAN, cryptogram, dynamic CVC  |
| `revoke` | `credentialId` or `grantId` | Revoke                             |
| `status` | `credentialId`              | Check status                       |

Redeem returns:

```json theme={}
{
  "type": "network_token",
  "dpan": "4XXX XXXX XXXX XXXX",
  "cryptogram": "AJkBBk...==",
  "dynamicCvc": "482",
  "eci": "05",
  "expiryMonth": 12,
  "expiryYear": 2028,
  "network": "visa"
}
```

<Warning>
  The DPAN is a Visa Network Token, not the FPAN. The internal `fillToken` is AES-256-GCM encrypted and is masked in MCP responses.
</Warning>

### `ovra_card`

Manage virtual cards. Credentials are issued via `ovra_credential`.

| Action     | Required                      | Description                      |
| ---------- | ----------------------------- | -------------------------------- |
| `issue`    | `agentId`, `usage`, `purpose` | Issue a new card                 |
| `list`     | `agentId`                     | List cards for an agent          |
| `freeze`   | `agentId`                     | Freeze (reversible)              |
| `unfreeze` | `agentId`                     | Resume                           |
| `close`    | `agentId`, `confirm: true`    | Permanent close                  |
| `rotate`   | `agentId`                     | Issue new credentials, close old |

### `ovra_policy`

Read-only by design. Modify policies through the dashboard or API key.

| Action | Required  | Description                 |
| ------ | --------- | --------------------------- |
| `get`  | `agentId` | Read agent's current policy |

### `ovra_transaction`

| Action | Required                | Description             |
| ------ | ----------------------- | ----------------------- |
| `get`  | `transactionId`         | Fetch detail            |
| `memo` | `transactionId`, `memo` | Annotate (audit-logged) |

### `ovra_receipt`

PDF only, base64-encoded, max 5 MB.

| Action   | Required                 | Description          |
| -------- | ------------------------ | -------------------- |
| `upload` | `intentId`, `fileBase64` | Attach a PDF receipt |
| `get`    | `intentId`               | Retrieve receipt     |

### `ovra_dispute`

| Action | Required                  | Description        |
| ------ | ------------------------- | ------------------ |
| `get`  | `disputeId`               | Fetch detail       |
| `file` | `transactionId`, `reason` | File a new dispute |

### `ovra_outcome`

Report payment outcomes for policy learning.

| Action   | Required                         | Description    |
| -------- | -------------------------------- | -------------- |
| `report` | `agentId`, `type`, `description` | Report outcome |

## Money-movement (6)

### `ovra_account`

| Action   | Required    | Description                    |
| -------- | ----------- | ------------------------------ |
| `get`    | `accountId` | Wallet detail                  |
| `create` | `name`      | Create wallet                  |
| `fund`   | `amount`    | Add funds (sandbox: simulated) |

### `ovra_payment`

| Action   | Required                                            | Description         |
| -------- | --------------------------------------------------- | ------------------- |
| `get`    | `paymentId`                                         | Fetch transfer      |
| `create` | `sourceAccountId`, `destinationType`, `amountEuros` | Create transfer     |
| `split`  | `sourceAccountId`, `legs`                           | Atomic 1-to-N split |

### `ovra_vendor`

| Action   | Required       | Description       |
| -------- | -------------- | ----------------- |
| `get`    | `vendorId`     | Fetch beneficiary |
| `create` | `name`, `iban` | Add beneficiary   |
| `delete` | `vendorId`     | Remove            |

### `ovra_workflow`

| Action | Required     | Description    |
| ------ | ------------ | -------------- |
| `get`  | `workflowId` | Fetch workflow |
| `end`  | `workflowId` | End workflow   |

### `ovra_authorization`

Delegations — issue scoped tokens to third parties.

| Action   | Required                         | Description               |
| -------- | -------------------------------- | ------------------------- |
| `get`    | `authorizationId`                | Fetch detail              |
| `create` | `permissions`, `expiresInHours`  | Create grant              |
| `redeem` | `authorizationId`, `acceptToken` | Redeem to mint `at_dlg_*` |
| `revoke` | `authorizationId`                | Revoke                    |

### `ovra_claim`

Collect — payment requests, links, invoices. Tool will rename to `ovra_collect` in a future MCP release; the actions are stable.

| Action           | Required                                            | Description            |
| ---------------- | --------------------------------------------------- | ---------------------- |
| `request_create` | `destinationAccountId`, `amountEuros`               | Create payment request |
| `request_list`   | –                                                   | List requests          |
| `request_get`    | `requestId`                                         | Fetch detail           |
| `request_settle` | `requestId`, `sourceAccountId`                      | Internal settle        |
| `request_cancel` | `requestId`                                         | Cancel                 |
| `link_create`    | `destinationAccountId`, `amountEuros`               | Create payment link    |
| `link_get`       | `linkId`                                            | Fetch link             |
| `link_void`      | `linkId`                                            | Void link              |
| `invoice_create` | `destinationAccountId`, `customerName`, `lineItems` | Create invoice         |
| `invoice_get`    | `invoiceId`                                         | Fetch invoice          |
| `invoice_void`   | `invoiceId`                                         | Void invoice           |

## Admin (4)

### `ovra_agent`

| Action         | Required                      | Description                                  |
| -------------- | ----------------------------- | -------------------------------------------- |
| `provision`    | `name`, `policyId`            | Create an agent                              |
| `get`          | `agentId`                     | Fetch detail                                 |
| `update`       | `agentId`                     | Update (status changes need `confirm: true`) |
| `issue_card`   | `agentId`, `usage`, `purpose` | Issue a card                                 |
| `token_list`   | `agentId`                     | List `at_*` tokens                           |
| `token_create` | `agentId`                     | Create scoped token                          |
| `token_revoke` | `agentId`, `tokenId`          | Revoke token                                 |

### `ovra_customer`

| Action         | Required        | Description                                  |
| -------------- | --------------- | -------------------------------------------- |
| `get`          | –               | Account profile                              |
| `update`       | –               | Update email, name, plan                     |
| `gdpr_export`  | –               | Export all personal data                     |
| `gdpr_consent` | –               | Get / update consent flags                   |
| `gdpr_delete`  | `confirm: true` | Anonymize (transactions retained per GwG §8) |

### `ovra_merchant`

Read-only merchant intelligence.

| Action    | Required | Description                              |
| --------- | -------- | ---------------------------------------- |
| `resolve` | `query`  | Merchant name → MCC + risk               |
| `explain` | `code`   | MCC → category + description             |
| `suggest` | `query`  | Purchase purpose → recommended allowlist |

### `ovra_config`

Read-only. Manage keys and webhooks via dashboard or API.

| Action         | Required | Description                      |
| -------------- | -------- | -------------------------------- |
| `key_list`     | –        | List API keys (secrets redacted) |
| `webhook_list` | –        | List webhook subscriptions       |

## Annotations

Every tool carries metadata that MCP-aware clients can use:

| Hint              | Meaning                              |
| ----------------- | ------------------------------------ |
| `readOnlyHint`    | Tool does not mutate state           |
| `destructiveHint` | Tool deletes or terminates something |
| `idempotentHint`  | Calling twice is safe                |

## Next

<CardGroup cols={2}>
  <Card title="MCP overview" icon="info" href="/mcp/overview">
    Architecture and security.
  </Card>

  <Card title="MCP setup" icon="terminal" href="/mcp/setup">
    Installation per client.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference">
    Full REST surface — every endpoint, every field.
  </Card>
</CardGroup>