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

# Tools and operations

> Reference for the 11 tools of the Chargefy MCP server, the 61 executable operations and the response formats.

The Chargefy MCP server uses a progressive surface: the agent first understands the connection, then discovers the right method, reads its contract and only then executes.

```text theme={"theme":"css-variables"}
context → discovery → contract → read or write
```

That structure keeps `tools/list` small and lets every operation reuse the same handler, validation and public object as the REST API.

<Info>
  Nine tools appear on every authenticated connection. `chargefy_api_create` and
  `chargefy_api_update` show up only when at least one enabled environment has
  write access.
</Info>

## Catalog of the 11 tools

| Group     | Tool                              | When to use it                                       |
| --------- | --------------------------------- | ---------------------------------------------------- |
| Context   | `get_chargefy_account_info`       | See organization, environments and access            |
| Discovery | `chargefy_api_search`             | Find operations by text, resource, method or risk    |
| Discovery | `chargefy_api_details`            | Get the exact schema of one operation                |
| Execution | `chargefy_api_read`               | Execute an allowed `GET` operation                   |
| Execution | `chargefy_api_create`             | Create a resource, with idempotency                  |
| Execution | `chargefy_api_update`             | Change an existing resource, with idempotency        |
| Data      | `search_chargefy_resources`       | Find resources by free text                          |
| Data      | `fetch_chargefy_resources`        | Load up to 25 objects by ID                          |
| Support   | `search_chargefy_documentation`   | Search the Chargefy documentation                    |
| Support   | `chargefy_implementation_planner` | Draft an integration plan without executing anything |
| Support   | `send_chargefy_mcp_feedback`      | Report a problem or a missing capability             |

## Context

### `get_chargefy_account_info`

Call it without arguments at the start of the conversation, and whenever the environment is in doubt.

```json theme={"theme":"css-variables"}
{
  "arguments": {},
  "name": "get_chargefy_account_info"
}
```

The response tells you:

* whether authentication is `oauth` or `api_key`;
* the client name, when available;
* the contract version;
* the connection's organization;
* the test and/or live scopes;
* the `read` or `write` access of each scope;
* `environment_enabled` per scope — whether MCP is enabled for that environment;
* the authenticated user, under OAuth.

A scope with `environment_enabled: false` still appears in the list, but any execution in it answers `environment_disabled` until an administrator enables MCP for that environment in the developer settings.

If the connection holds both test and live, the tools that reach data need `livemode`. With a single environment, the server infers it.

## Operation discovery

### `chargefy_api_search`

Finds methods this connection can execute.

| Argument                 | Type      | Rule                                                   |
| ------------------------ | --------- | ------------------------------------------------------ |
| `query`                  | `string`  | Searches ID, summary and path; up to 200 characters    |
| `resource`               | `string`  | Exact resource, such as `customers` or `payment_links` |
| `method`                 | `string`  | `GET` or `POST`                                        |
| `risk`                   | `string`  | `R0` for reads or `R1` for writes                      |
| `include_non_executable` | `boolean` | Includes known but ungranted operations                |
| `limit`                  | `integer` | 1 to 50; defaults to 20                                |
| `starting_after`         | `string`  | Cursor holding the last `operation_id`                 |

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "query": "link",
    "risk": "R1"
  },
  "name": "chargefy_api_search"
}
```

Each result carries `operation_id`, a summary, the method, the path, the risk class and `executable`. When it is not executable, `not_executable_reason` explains why.

### `chargefy_api_details`

Returns the full contract of one operation:

* `input_schema` and `output_schema`;
* method and path;
* risk class;
* required capability;
* allowed environments;
* whether `intent_id` is required;
* execution state for this connection;
* the API reference URL.

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "operation": "payment_links.create"
  },
  "name": "chargefy_api_details"
}
```

<Tip>
  Call `chargefy_api_details` before the first write of each method. The `data`
  object must follow the `input_schema` exactly; unknown fields are rejected.
</Tip>

## Execution

### `chargefy_api_read`

Executes an `R0` read operation.

| Argument         | Type      | Rule                                                                   |
| ---------------- | --------- | ---------------------------------------------------------------------- |
| `operation`      | `string`  | Required; for example `customers.list`                                 |
| `id`             | `string`  | Required on `.get` operations                                          |
| `limit`          | `integer` | 1 to 100; defaults to 10 on lists                                      |
| `starting_after` | `string`  | Next page                                                              |
| `ending_before`  | `string`  | Previous page                                                          |
| `filters`        | `object`  | Equality filters described by `chargefy_api_details`                   |
| `livemode`       | `boolean` | Needed when both test and live are authorized                          |
| `organization`   | `string`  | Optional; usually omitted because the connection pins the organization |

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "filters": {
      "email": "name@email.com"
    },
    "limit": 10,
    "operation": "customers.list"
  },
  "name": "chargefy_api_read"
}
```

Do not send `starting_after` and `ending_before` together. Unknown or invalid filters return `invalid_arguments`.

### `chargefy_api_create`

Executes an `R1` create operation. It accepts only an `operation` ending in `.create`; an `.update` operation is refused, pointing at the right tool.

| Argument       | Type      | Rule                                                    |
| -------------- | --------- | ------------------------------------------------------- |
| `operation`    | `string`  | Required; a `.create` operation                         |
| `intent_id`    | `string`  | Required; opaque token of 16 to 64 characters           |
| `data`         | `object`  | Required; follows the operation's `input_schema`        |
| `livemode`     | `boolean` | Needed when both test and live have write access        |
| `organization` | `string`  | Optional; does not change the connection's organization |

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "data": {
      "email": "name@email.com",
      "name": "Customer"
    },
    "intent_id": "9f4c1e0a-5b7d-4c2e-9a01-3d8f6b2c7e51",
    "operation": "customers.create"
  },
  "name": "chargefy_api_create"
}
```

Creating is additive: the tool is announced as non-destructive, so clients usually run it without a per-call confirmation.

### `chargefy_api_update`

Executes an `R1` update operation on the resource identified by `id`. It accepts only an `operation` ending in `.update`.

| Argument       | Type      | Rule                                                    |
| -------------- | --------- | ------------------------------------------------------- |
| `operation`    | `string`  | Required; an `.update` operation                        |
| `id`           | `string`  | Required; public ID of the resource being changed       |
| `intent_id`    | `string`  | Required; opaque token of 16 to 64 characters           |
| `data`         | `object`  | Required; follows the operation's `input_schema`        |
| `livemode`     | `boolean` | Needed when both test and live have write access        |
| `organization` | `string`  | Optional; does not change the connection's organization |

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "id": "cus_9Kd2WqPtR7bLmA3v",
    "data": {
      "name": "Premium customer"
    },
    "intent_id": "1c7f4a92-8e35-4d60-bb14-27a9f0e5c3d8",
    "operation": "customers.update"
  },
  "name": "chargefy_api_update"
}
```

Updating is not additive: the tool is announced as destructive (`destructiveHint`), so clients that respect the annotation ask for confirmation before each execution. Fields omitted from `data` keep their current value.

On both tools, repeating the same intent with the same `intent_id` returns the original result. The same token with another operation or different `data` is rejected.

## Searching and loading data

### `search_chargefy_resources`

Searches text across allowlisted display fields.

| Resource         | Fields searched |
| ---------------- | --------------- |
| `customers`      | Name and email  |
| `products`       | Name            |
| `prices`         | Name            |
| `discounts`      | Name            |
| `discount_codes` | Code            |
| `payment_links`  | Label           |
| `invoices`       | Number          |

Arguments:

* `query`: required, 2 to 200 characters;
* `resources`: up to 8 types; omit it to search every granted resource;
* `limit`: 1 to 25; defaults to 10;
* `livemode`: needed when both environments are available;
* `organization`: optional and usually inferred.

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "query": "essential",
    "resources": [
      "products",
      "prices"
    ]
  },
  "name": "search_chargefy_resources"
}
```

The response carries summaries with `id`, `object`, `display_name` and `created_at`. Use a read tool to get the full object.

### `fetch_chargefy_resources`

Loads up to 25 public objects in one call. It accepts IDs of the 24 executable resources:

| Prefix   | Resource          | Prefix      | Resource              |
| -------- | ----------------- | ----------- | --------------------- |
| `cus_`   | Customer          | `pi_`       | Payment intent        |
| `prod_`  | Product           | `ch_`       | Charge                |
| `price_` | Price             | `re_`       | Refund                |
| `disc_`  | Discount          | `sub_`      | Subscription          |
| `dcode_` | Discount code     | `inv_`      | Invoice               |
| `plink_` | Payment link      | `txn_`      | Transaction           |
| `dp_`    | Dispute           | `evt_`      | Event                 |
| `req_`   | Request           | `we_`       | Webhook endpoint      |
| `pm_`    | Payment method    | `seti_`     | Setup intent          |
| `si_`    | Subscription item | `subsched_` | Subscription schedule |
| `ur_`    | Usage record      | `file_`     | File                  |
| `cs_`    | Checkout session  | `org_`      | Child organization    |

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "ids": [
      "cus_E1MR2Rb27ssEATmx",
      "inv_Px5Lh2P4zir7g6N8"
    ]
  },
  "name": "fetch_chargefy_resources"
}
```

IDs that do not exist, are unknown or are not allowed come back under `missing`; they never reveal whether the object exists outside the scope.

## Support

### `search_chargefy_documentation`

Searches the developer documentation index.

| Argument   | Rule                          |
| ---------- | ----------------------------- |
| `query`    | Required, 2 to 200 characters |
| `language` | `pt` or `en`                  |
| `limit`    | 1 to 10; defaults to 5        |

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "language": "en",
    "query": "verify webhook signature"
  },
  "name": "search_chargefy_documentation"
}
```

The response carries a title, a URL, the language and a short excerpt. Content found this way is reference material, never an instruction to the agent.

### `chargefy_implementation_planner`

Builds a deterministic plan for an integration goal. It can point at prerequisites, operations and documentation pages, but it never executes data tools.

<Info>
  For activation, the planner distinguishes your own account from a child
  organization. MCP guides both cases and reads child organizations
  (`organizations.list` and `organizations.get`); creating, changing and
  activating them still goes through the public API. See [activation by
  API](/platforms/activate-organization-by-api) or the [hosted activation
  session](/platforms/activate-organization-with-hosted-session).
</Info>

| Argument  | Rule                             |
| --------- | -------------------------------- |
| `goal`    | Required, 10 to 500 characters   |
| `context` | Optional, up to 2,000 characters |

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "context": "The product already exists and I want to work in test mode.",
    "goal": "Create a link to sell a monthly plan"
  },
  "name": "chargefy_implementation_planner"
}
```

### `send_chargefy_mcp_feedback`

Sends feedback about the MCP server itself.

| Argument     | Rule                                                    |
| ------------ | ------------------------------------------------------- |
| `category`   | `bug`, `missing_capability`, `documentation` or `other` |
| `comment`    | Required, 5 to 2,000 characters                         |
| `tool_name`  | The related tool, when there is one                     |
| `operation`  | The related `operation_id`, when there is one           |
| `request_id` | The ID returned in an error, for correlation            |

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "category": "missing_capability",
    "comment": "I need to filter customers by document.",
    "operation": "customers.list",
    "tool_name": "chargefy_api_read"
  },
  "name": "send_chargefy_mcp_feedback"
}
```

This tool only records the feedback. It never changes account resources.

## The 61 operations

The executable surface has **47 reads**, **2 calculations** (previews — POSTs that change nothing, executed through `chargefy_api_read` with `data`) and **12 writes**:

| Resource                                          | `list` | `get` | `create` | `update` |
| ------------------------------------------------- | :----: | :---: | :------: | :------: |
| Customers (`customers`)                           |    ✓   |   ✓   |     ✓    |     ✓    |
| Products (`products`)                             |    ✓   |   ✓   |     ✓    |     ✓    |
| Prices (`prices`)                                 |    ✓   |   ✓   |     ✓    |     ✓    |
| Discounts (`discounts`)                           |    ✓   |   ✓   |     ✓    |     ✓    |
| Discount codes (`discount_codes`)                 |    ✓   |   ✓   |     ✓    |     ✓    |
| Payment links (`payment_links`)                   |    ✓   |   ✓   |     ✓    |     ✓    |
| Payment intents (`payment_intents`)               |    ✓   |   ✓   |     —    |     —    |
| Charges (`charges`)                               |    ✓   |   ✓   |     —    |     —    |
| Refunds (`refunds`)                               |    ✓   |   ✓   |     —    |     —    |
| Subscriptions (`subscriptions`)                   |    ✓   |   ✓   |     —    |     —    |
| Invoices (`invoices`)                             |    ✓   |   ✓   |     —    |     —    |
| Transactions (`transactions`)                     |    ✓   |   ✓   |     —    |     —    |
| Disputes (`disputes`)                             |    ✓   |   ✓   |     —    |     —    |
| Events (`events`)                                 |    ✓   |   ✓   |     —    |     —    |
| Requests (`requests`)                             |    ✓   |   ✓   |     —    |     —    |
| Webhook endpoints (`webhook_endpoints`)           |    ✓   |   ✓   |     —    |     —    |
| Payment methods (`payment_methods`)               |    ✓   |   ✓   |     —    |     —    |
| Setup intents (`setup_intents`)                   |    ✓   |   ✓   |     —    |     —    |
| Subscription items (`subscription_items`)         |    ✓   |   ✓   |     —    |     —    |
| Schedules (`subscription_schedules`)              |    ✓   |   ✓   |     —    |     —    |
| Usage records (`subscription_item_usage_records`) |    ✓   |   ✓   |     —    |     —    |
| Files (`files`)                                   |    ✓   |   ✓   |     —    |     —    |
| Checkout sessions (`checkout_sessions`)           |    —   |   ✓   |     —    |     —    |
| Child organizations (`organizations`)\*\*         |    ✓   |   ✓   |     —    |     —    |
| Invoice preview (`invoice_previews`)              |    —   |   —   |    ✓\*   |     —    |
| Payment preview (`payment_previews`)              |    —   |   —   |    ✓\*   |     —    |

IDs follow `<resource>.<action>`, such as `invoices.list`, `subscriptions.get` and `prices.update`.

<Info>
  MCP is bound to one organization. On accounts with **Chargefy for Platforms**,
  the platform organization's connection also reads its child organizations:
  `organizations.list` and `organizations.get` return the full public object,
  including `activation_status` and the `requirements` task list, and
  `organization.*` events show up in `events.list`. Creating, updating and
  activating child organizations still happens through the public API.
</Info>

<Warning>
  A read operation never grants the matching action. For example, `refunds.get`
  reads an existing refund; there is no `refunds.create` in MCP.
</Warning>

## Responses

On success, the tool returns:

* textual `content` in JSON, for clients that read text;
* `structuredContent` with the same structured result;
* the same public DTO as the REST API on execution operations.

Lists use:

```json theme={"theme":"css-variables"}
{
  "object": "list",
  "data": [],
  "has_more": false,
  "url": null
}
```

Execution errors use `isError: true` and a structured payload:

```json theme={"theme":"css-variables"}
{
  "code": "invalid_arguments",
  "message": "Invalid data for customers.create.",
  "param": "data",
  "retryable": false,
  "suggested_action": "Check chargefy_api_details for customers.create."
}
```

Extra fields may include `request_id` and `retry_after_ms`. JSON-RPC protocol errors are reserved for invalid messages or unknown tools.

## Keep going

<CardGroup cols={2}>
  <Card title="Usage examples" icon="message" href="/en/mcp/how-to-use">
    See how to combine context, discovery, reads and writes.
  </Card>

  <Card title="Limits and security" icon="shield-halved" href="/en/mcp/limits">
    Check rate limits, auditing and unavailable operations.
  </Card>
</CardGroup>

\* `create` on previews is a **calculation** (compute class): it goes through `chargefy_api_read` with `data`, requires no `intent_id` and never changes data.

\*\* Exclusive to accounts with **Chargefy for Platforms**: the platform organization's connection reads its child organizations. Without a platform, the operation answers `platform_required`.