# RevCent MCP Guide: `SearchCustomerCards`

AI/MCP-focused guide for searching RevCent Customer Cards.

---

## Related Documentation

| Guide | Link | Why It Matters |
|---|---|---|
| Customer Card Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewCustomerCard.md` | Required overview for understanding Customer Cards, safe card summaries, default payment method behavior, and Customer Card lifecycle. |
| Customer Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewCustomer.md` | Explains Customers and how Customer Cards attach to Customer records. |
| GetCustomer | `https://revcent.com/documentation/markdown/mcp/operation/GetCustomer.md` | Retrieve the Customer connected to the card. |
| AddCardToCustomer | `https://revcent.com/documentation/markdown/mcp/operation/AddCardToCustomer.md` | Add a new card to an existing Customer. |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` | Correct operation for reporting, metrics, aggregation, and data mining. |


---

## Operation Summary

Operation:

```text
SearchCustomerCards
```

Title:

```text
Search Customer Cards
```

Purpose:

```text
Search previously created Customer Cards using a search term.
```

Use `SearchCustomerCards` when the exact Customer Card ID is unknown and the user provides a search term such as customer email, customer name, phone, address, first 6, last 4, expiration date, metadata, or another searchable phrase.

---

## Input Schema

| Field | Type | Required | Description |
|---|---:|---:|---|
| `search_term` | string | Yes | Single search term or phrase used by the full-text search engine. |

Example:

```json
{
  "search_term": "4242"
}
```

---

## Output Summary

Search results can include:

| Field | Meaning |
|---|---|
| `item_type` | Always `customer_card`. |
| `id` | 20-character Customer Card ID. |
| `customer_id` | 20-character Customer ID. |
| `created_date_unix` | Customer Card creation timestamp. |
| `first_name` / `last_name` | Customer name. |
| `email` | Customer email. |
| `phone` | Customer phone. |
| `address_line_1`, `city`, `state`, `zip` | Customer address search fields. |
| `first_6` | First 6 digits/BIN. |
| `last_4` | Last 4 digits. |
| `expiration_date` | Expiration date as `MMYY`. |
| `metadata` | Metadata name/value pairs. |
| `url` | Direct RevCent details URL. |
| `highlights` | Search-highlighted fields and values. |
| `score` | Search score; higher is a better match. |

---

## Search Safety Rule

Search results are possible matches, not proof of authorization.

Before sharing card details or taking card action:

```text
SearchCustomerCards
    ↓
Select likely result
    ↓
GetCustomerCard
    ↓
Verify related Customer using a secondary record-backed value
    ↓
Only then provide limited details or run a card operation
```

Do not enable, disable, delete, or set a card as default directly from a search result.

---

## Customer-Facing AI Verification Warning

Customer Card records are sensitive payment-method records, even though RevCent only returns safe card summaries such as card type, first 6/BIN, last 4, and expiry.

If this operation is used inside a customer-facing AI flow, such as:

- AI Voice Agent,
- public chatbot,
- customer portal assistant,
- SMS assistant,
- any visitor-facing AI workflow,

AI/MCP should verify that the visitor is actually the Customer or is otherwise authorized before providing card details or taking action.

Recommended rule:

```text
Do not provide Customer Card details or perform Customer Card actions based only on visitor-provided input.
```

Use a secondary value from the retrieved RevCent record, such as customer email or phone from `GetCustomerCard.customer`, `GetCustomer`, or another related record.

Safe flow:

```text
Visitor provides customer/card input
    ↓
AI locates/retrieves the Customer Card
    ↓
AI retrieves or reviews the related Customer
    ↓
AI verifies a secondary value from the retrieved RevCent record
    ↓
AI confirms the requested action
    ↓
Only then provides limited information or performs the operation
```

Do not disclose or request full card numbers, CVV/card code, secrets, or payment credentials in normal public chat. Use secure PCI-appropriate payment collection flows for adding cards.


---

## Reporting Guidance

This operation is not a reporting or analytics tool.

Do not use Customer Card lookup/search or mutation operations for:

- counting,
- aggregations,
- metrics,
- reporting,
- data mining,
- bulk retrieval,
- broad analysis,
- card portfolio analysis,
- card expiry reports,
- default-card reports,
- payment-method performance reports,
- customer segmentation reports.

Use:

```text
BigQueryRunQuery
```

for those purposes.

Important AI/MCP behavior:

```text
If AI/MCP intended to use this operation for reporting, metrics, aggregation, or data mining and then realizes BigQueryRunQuery is the correct operation, it does not need to tell the user about the correction.

It should simply use BigQueryRunQuery instead.
```



---

## Correct Use vs Incorrect Use

| User Intent | Correct Action |
|---|---|
| “Find the card ending in 4242.” | Use `SearchCustomerCards`, then `GetCustomerCard`. |
| “Find cards for this customer email.” | Use `SearchCustomerCards`, then verify with `GetCustomerCard`/`GetCustomer`. |
| “How many cards expire this month?” | Use `BigQueryRunQuery`, not `SearchCustomerCards`. |
| “Analyze cards by BIN.” | Use `BigQueryRunQuery`, not `SearchCustomerCards`. |

---

## Final AI/MCP Instruction

Use `SearchCustomerCards` only for targeted lookup when the Customer Card ID is unknown. In customer-facing AI flows, verify the related Customer using a secondary value from the retrieved record before sharing details or taking action. Use `BigQueryRunQuery` for analytics.


---
Document Parent Directory
* [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.