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

# Tools Reference

> Complete reference for all CRM MCP tools

# Tools Reference

The CRM MCP server exposes **13 read-only diagnostic tools** scoped to a single TagadaPay account. All tools are backed by the official [`@tagadapay/node-sdk`](/developer-tools/node-sdk/quick-start).

<Note>
  All tools are implicitly account-scoped — you never pass an `accountId`. The API key in your MCP config determines which account you see.
</Note>

The tools are organized in six categories: **Orders**, **Stores**, **Processors**, **Funnels**, **Customers**, **Webhooks & domains**.

***

## Orders

### `orders.list`

List orders for the account with optional filters and pagination.

| Parameter  | Type      | Required | Default | Description            |
| ---------- | --------- | -------- | ------- | ---------------------- |
| `storeId`  | string    | No       | —       | Filter by store id     |
| `status`   | string\[] | No       | —       | Filter by order status |
| `page`     | number    | No       | `1`     | Page number, 1-indexed |
| `pageSize` | number    | No       | `25`    | Page size, max `100`   |

**Returns:** `{ total, page, pageSize, count, items: [...] }`

### `orders.retrieve`

Retrieve a single order by id.

| Parameter | Type   | Required | Description              |
| --------- | ------ | -------- | ------------------------ |
| `orderId` | string | Yes      | Order id, e.g. `ord_xxx` |

**Returns:** the order object.

***

## Stores

### `stores.list`

List stores on the account.

| Parameter  | Type   | Required | Default | Description          |
| ---------- | ------ | -------- | ------- | -------------------- |
| `page`     | number | No       | `1`     | Page number          |
| `pageSize` | number | No       | `25`    | Page size, max `100` |

**Returns:** `{ total, page, pageSize, items: [...] }`

### `stores.retrieve`

Retrieve a single store by id.

| Parameter | Type   | Required | Description                |
| --------- | ------ | -------- | -------------------------- |
| `storeId` | string | Yes      | Store id, e.g. `store_xxx` |

**Returns:** the store object.

***

## Processors

Useful first call when an agent is asked about declined payments or routing.

### `processors.list`

List payment processors configured on the account, with their `active` flag, supported `currencies`, and `countries`.

*No parameters.*

**Returns:** `{ count, items: [...] }`

### `processors.retrieve`

Retrieve a single processor by id.

| Parameter     | Type   | Required | Description                   |
| ------------- | ------ | -------- | ----------------------------- |
| `processorId` | string | Yes      | Processor id, e.g. `proc_xxx` |

**Returns:** the processor object.

***

## Funnels

### `funnels.list`

List funnels for a store. Use to diagnose checkout issues (wrong default currency, inactive funnel, missing steps).

| Parameter | Type   | Required | Description                |
| --------- | ------ | -------- | -------------------------- |
| `storeId` | string | Yes      | Store id, e.g. `store_xxx` |

**Returns:** `{ count, items: [...] }`

### `funnels.retrieve`

Retrieve a single funnel by id with its full configuration.

| Parameter  | Type   | Required | Description               |
| ---------- | ------ | -------- | ------------------------- |
| `funnelId` | string | Yes      | Funnel id, e.g. `fnl_xxx` |

**Returns:** the funnel object with steps and offer config.

***

## Customers

### `customers.list`

List customers with optional email filter and pagination.

| Parameter  | Type   | Required | Default | Description                 |
| ---------- | ------ | -------- | ------- | --------------------------- |
| `email`    | string | No       | —       | Filter by exact email match |
| `page`     | number | No       | `1`     | Page number                 |
| `pageSize` | number | No       | `25`    | Page size, max `100`        |

**Returns:** `{ total, page, pageSize, items: [...] }`

### `customers.retrieve`

Retrieve a single customer by id.

| Parameter    | Type   | Required | Description                 |
| ------------ | ------ | -------- | --------------------------- |
| `customerId` | string | Yes      | Customer id, e.g. `cus_xxx` |

**Returns:** the customer object.

***

## Webhooks & domains

### `webhooks.list`

List webhook endpoints configured on a store. Use to diagnose missing or misconfigured endpoints.

| Parameter | Type   | Required | Description                |
| --------- | ------ | -------- | -------------------------- |
| `storeId` | string | Yes      | Store id, e.g. `store_xxx` |

**Returns:** `{ count, items: [...] }`

### `domains.list`

List custom domains on the account with their verification status.

*No parameters.*

**Returns:** `{ count, items: [...] }`

### `domains.getDnsLookup`

Live DNS lookup for a domain — returns the actual A/CNAME/TXT records observed on the public internet, run from TagadaPay infrastructure. Use to diagnose DNS misconfiguration without making the merchant run `dig`.

| Parameter    | Type   | Required | Description                                    |
| ------------ | ------ | -------- | ---------------------------------------------- |
| `domain`     | string | Yes      | Domain name, e.g. `shop.example.com`           |
| `recordType` | enum   | No       | One of `A`, `AAAA`, `CNAME`, `TXT`, `MX`, `NS` |

**Returns:** the DNS lookup result.

***

## Errors

| Error code       | When it happens                   | What to do                               |
| ---------------- | --------------------------------- | ---------------------------------------- |
| `unauthorized`   | API key missing or revoked        | Re-issue from Settings → API Keys        |
| `forbidden`      | Key exists but lacks `read` scope | Update the key's scope                   |
| `rate_limited`   | Too many calls from one key       | Back off; retry with exponential backoff |
| `internal_error` | Transient server error            | Retry once; report if persistent         |

Errors are surfaced to the MCP client with `isError: true` and a human-readable message.

## Versioning

The tool surface follows semantic versioning of `@tagadapay/crm-mcp`:

* **Patch** (`1.x.y`): bug fixes, schema clarifications.
* **Minor** (`1.x.0`): new tools, additive fields. Existing tools never break.
* **Major** (`x.0.0`): breaking changes, telegraphed in the changelog at least one minor release ahead.

Tools never silently change their input or output schema between minor versions.

## Adding tools (for contributors)

The MCP surface is **strictly read-only**. If a proposed tool mutates server state, it belongs in the in-app auto-fix agent's proposal flow — not here. New tool PRs must:

1. Call a TagadaPay Node SDK method that does not mutate server state.
2. Validate inputs with Zod.
3. Use `txt()` / `err()` helpers for consistent response shapes.
4. Not introduce new SDK dependencies beyond `@tagadapay/node-sdk`.