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

# list_cards

> List your organization's cards in this mode, newest first.

Connect to `https://mcp.agentcard.sh/mcp` with your **organization credential** (`client_id` + `client_secret`, or the org access token).

**Behavior:** read-only.

## What it does

List your organization's cards in this mode, newest first. Filter by cardholder or status (OPEN, IN\_USE, CLOSED, PAUSED, PAUSING, CLOSING). A card shows PAUSING or CLOSING from the moment a charge pauses or spends it until the card network confirms, then PAUSED or CLOSED; it finishes on its own.

## Inputs

| Field           | Type                                                                    | Description                                                                                                               |
| --------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `cardholder_id` | string                                                                  | Only this cardholder's cards                                                                                              |
| `status`        | string: `OPEN` · `IN_USE` · `CLOSED` · `PAUSED` · `PAUSING` · `CLOSING` | Only cards in this status. `PAUSING` and `CLOSING`: the change is recorded and the card network has not confirmed it yet. |
| `limit`         | number                                                                  | Max results (default 50, max 100)                                                                                         |
| `offset`        | number                                                                  | Pagination offset                                                                                                         |

## Returns

| Field                  | Type   | Description                                                                                                      |
| ---------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| `message` *(required)* | string | Human-readable summary.                                                                                          |
| `cards`                | array  | Card objects: `id`, `cardholderId`, `last4`, `expiry`, `spendLimitCents`, `balanceCents`, `status`, `createdAt`. |
| `total`                | number | Total cards matching the filter.                                                                                 |

## Example call

```json theme={null}
{
  "tool": "list_cards",
  "arguments": {}
}
```