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

# MCP Tools Reference

> Technical reference for the tools exposed by Clara MCP — parameters, behavior, and example outputs.

<Note>
  Clara MCP is in Beta. The toolset will expand significantly in the coming weeks to cover expenses, reimbursements, limits, and approvals.
</Note>

## Authentication

All tools require the `clara-mcp-token` header set during configuration. The token is scoped to the authenticated user's company — tools return data for that company only.

Supported roles: **Administrator**, **Bookkeeper**. Other roles are not supported in this version.

***

## list\_cards

Returns all corporate cards for the company.

**No input parameters required.**

### Example Output

```json theme={null}
[
  {
    "cardholderName": "Ana García",
    "lastFourDigits": "3540",
    "status": "ACTIVE",
    "spendingLimit": 10000.00,
    "currency": "MXN"
  },
  {
    "cardholderName": "Luis Pérez",
    "lastFourDigits": "7821",
    "status": "LOCKED",
    "spendingLimit": 5000.00,
    "currency": "MXN"
  }
]
```

### Example Prompts

* "List all my corporate cards"
* "Which cards are currently locked?"
* "List all cards with a spending limit above \$10,000"
* "Show me the card assigned to Ana García"

***

## list\_transactions

Returns card transactions for the company, with optional filters.

### Filters (Optional)

| Filter     | Type             | Format                                                                               | Example                                      |
| ---------- | ---------------- | ------------------------------------------------------------------------------------ | -------------------------------------------- |
| Card       | string           | Cardholder name or last 4 digits of card number                                      | "transactions on card 3540"                  |
| Date range | string (date)    | ISO 8601 (`YYYY-MM-DD`) or relative ("last 30 days", "this month")                   | "transactions from 2026-04-01 to 2026-04-30" |
| Amount     | number (decimal) | Currency units, not cents. Comparison operators supported (over, under, between)     | "transactions over 5000"                     |
| Category   | string (enum)    | MCC category name: `TRAVEL`, `FOOD`, `SOFTWARE_AND_HARDWARE`, `TRANSPORTATION`, etc. | "travel expenses last 90 days"               |

Filters can be combined freely in natural language — the AI assistant resolves them before calling the tool.

**Edge cases:**

* If no date range is specified, results default to the current billing period.
* If no results match the filters, the tool returns an empty `transactions` array — not an error.
* `totalCount` reflects the number of transactions returned, not the total in the account.

### Example Output

```json theme={null}
{
  "transactions": [
    {
      "id": "txn_abc123",
      "date": "2026-05-15T14:32:00Z",
      "amount": 1250.00,
      "currency": "MXN",
      "merchant": "Aeromexico",
      "category": "TRAVEL",
      "cardLastFour": "3540",
      "cardholderName": "Ana García",
      "status": "APPROVED"
    }
  ],
  "totalCount": 42
}
```

### Example Prompts

* "Show my transactions this month"
* "What were the top 5 vendors this quarter by total spend?"
* "Show all transactions labeled as travel expenses in the last 90 days"
* "What were our company's top spending categories last month?"
* "Show me the last 10 transactions on the card assigned to Ana García"

***

## lock\_card

Immediately locks a specific card. The cardholder cannot make purchases while the card is locked.

### Input

The card can be identified by cardholder name or last 4 digits. The AI assistant resolves the card before calling the tool.

### Behavior

* The lock takes effect immediately.
* In Beta, the confirmation response may appear as plain text ("Ok") rather than a structured message. The operation completes correctly regardless.
* The card can be unlocked at any time using `unlock_card`.

### Example Prompts

* "Lock the card ending in 3540 immediately"
* "Lock Luis Pérez's card"
* "Block the card assigned to the marketing team"

***

## unlock\_card

Immediately unlocks a previously locked card.

### Input

The card can be identified by cardholder name or last 4 digits.

### Behavior

* The unlock takes effect immediately.
* Same Beta display limitation as `lock_card` — the operation completes correctly.

### Example Prompts

* "Unlock the card ending in 7821"
* "Unblock Ana García's card"

***

## Coming Soon

The following capabilities are planned for upcoming Beta releases:

* Expense management and categorization
* Reimbursement requests and status
* Spending limit adjustments
* Approval workflows
* Budget overview by department or cost center