> ## 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 overview

> 19 action-multiplexed tools that give any LLM client full access to Ovra.

`@ovra/mcp` is the canonical way to give an LLM payment capabilities. It implements the [Model Context Protocol](https://modelcontextprotocol.io) and exposes Ovra's full surface — **19 tools** organized in three groups — over Streamable HTTP and stdio.

Tools are designed for LLMs, not humans. Each tool uses an `action` parameter to multiplex operations (e.g. `ovra_card { action: "issue", ... }`), descriptions are written for model consumption, and required-field gating uses JSON Schema `if/then` so the model gets clear errors.

<Note>
  Sandbox-only today. Use a `sk_sandbox_*` or `sk_test_*` key. Live mode opens in v1.3+.
</Note>

## Transports

<CardGroup cols={2}>
  <Card title="Streamable HTTP" icon="cloud">
    Remote, no install needed. Best for production.
    `https://api.getovra.com/api/mcp`
  </Card>

  <Card title="Stdio" icon="terminal">
    Local subprocess via `npx @ovra/mcp@latest`. Best for desktop clients.
  </Card>
</CardGroup>

## Supported clients

Anything that speaks MCP: Claude Desktop, Claude Code, Cursor, Kiro, OpenAI Agents SDK, LangGraph (via `langchain-mcp-adapters`), CrewAI, custom clients.

## The 19 tools

### Agent tools (9) — what an agent calls directly

| Tool               | Purpose                                                      |
| ------------------ | ------------------------------------------------------------ |
| `ovra_pay`         | Full payment flow — handles 402, intent, credential, present |
| `ovra_intent`      | Declare, get, cancel, verify intents                         |
| `ovra_credential`  | Grant, issue, redeem, revoke payment credentials             |
| `ovra_card`        | Issue, list, freeze, unfreeze, close, rotate cards           |
| `ovra_policy`      | Read agent policy (read-only — agents cannot modify)         |
| `ovra_transaction` | Get, memo                                                    |
| `ovra_receipt`     | Upload, retrieve PDF receipts (≤5 MB, base64)                |
| `ovra_dispute`     | File and inspect disputes                                    |
| `ovra_outcome`     | Report payment outcomes for policy learning                  |

### Money-movement (6) — wallets, vendors, workflows

| Tool                 | Purpose                                                                                              |
| -------------------- | ---------------------------------------------------------------------------------------------------- |
| `ovra_account`       | Wallet get/create/fund                                                                               |
| `ovra_payment`       | Transfers — get/create/split                                                                         |
| `ovra_vendor`        | Beneficiaries — get/create/delete                                                                    |
| `ovra_workflow`      | Multi-step payment workflows                                                                         |
| `ovra_authorization` | Delegations — create/redeem/revoke                                                                   |
| `ovra_claim`         | Collect — payment requests, links, invoices (tool will rename to `ovra_collect` in a future release) |

### Admin (4) — configuration, cross-cutting

| Tool            | Purpose                                            |
| --------------- | -------------------------------------------------- |
| `ovra_agent`    | Provision, get, update agents; manage agent tokens |
| `ovra_customer` | Account profile + GDPR (export, consent, delete)   |
| `ovra_merchant` | MCC lookup, merchant intelligence (read-only)      |
| `ovra_config`   | List API keys (redacted) and webhooks              |

See [tool reference](/mcp/tools) for every action and parameter.

## Two-mode payment flow

```text theme={}
User: "Buy a USB-C hub under EUR 30 on amazon.de"

Agent picks based on merchant capabilities:

  MPP-aware merchant ─► ovra_pay { action: "checkout", ... }   (one call)
  Form-only merchant ─► ovra_pay { action: "handle_402", ... } + CUA harness
```

For fine-grained control, use `ovra_intent` + `ovra_credential` directly.

## Security

* **Response redaction.** Every tool response goes through a redact pass — PAN, CVV, API keys, webhook secrets are masked before they enter model context.
* **Confirmation gates.** Destructive actions (`card.close`, `gdpr_delete`, `token_revoke`) require explicit `confirm: true`.
* **Input validation.** Required parameters enforced via `if/then`. IDs sanitized against path traversal.
* **URL validation.** Webhook and execute URLs must be HTTPS, SSRF-checked.
* **Tool annotations.** Every tool carries `readOnlyHint`, `destructiveHint`, `idempotentHint` metadata so MCP-aware clients can warn users.

## Sacred guarantees through MCP

* PAN/CVV physically cannot reach the model — server-side redaction plus the credential boundary.
* `requireIntent` enforced server-side; an `ovra_pay` call without an approved intent returns a structured error, never a charge.
* Strict agent isolation — `at_*` tokens see only their own agent's data.

## Next

<CardGroup cols={2}>
  <Card title="Setup" icon="terminal" href="/mcp/setup">
    Install and configure for your client.
  </Card>

  <Card title="Tool reference" icon="book" href="/mcp/tools">
    Every tool, every action, every parameter.
  </Card>

  <Card title="Claude Desktop" icon="comments" href="/integrations/claude-desktop">
    The simplest possible client.
  </Card>

  <Card title="OpenAI Agents" icon="brain" href="/integrations/openai-agents">
    Hosted MCP integration.
  </Card>
</CardGroup>