Usage examples

You make the request in your own words and the assistant assembles the calls. The examples below show the request and, right below it, the JSON of the call the assistant makes. The JSON is there for you to check what is going on, not to type.

The safest way to use it

A good assistant follows five steps before changing anything:

Checks where it is

Calls get_chargefy_account_info to learn the connection’s organization, environment and access level.

Discovers the right operation

Uses chargefy_api_search instead of guessing the operation name.

Reads the contract

Checks chargefy_api_details to learn which fields the operation accepts, especially before creating or changing something.

Looks at the current state

Reads the resource or finds the right ID before changing it.

Changes with confirmation and duplicate protection

Shows the operation, the data, the ID and the environment for you to approve; then executes with a new intent_id.

Human confirmation happens in the assistant, not on Chargefy’s server. The server checks permission, data format and duplicates, but it does not open a confirmation screen on every change. That is why it is worth asking explicitly: “show me before executing”. Updates (chargefy_api_update) are marked as destructive, and most assistants ask for confirmation before them on their own.

Recommended opening prompt

Use the Chargefy connection. First show the organization, the environments and the access level. Work in test. Do reads only until I authorize a change. Before any write, show the tool, the operation, the IDs, the data and the intent_id.

That request avoids the three most common mistakes: touching the wrong environment, guessing the operation and changing something without you seeing it first.

Querying data

List customers

Ask:

List the 10 most recent customers in the test environment. Do not change data.

After checking the context, the assistant makes this call:

{
  "arguments": {
    "limit": 10,
    "livemode": false,
    "operation": "customers.list"
  },
  "name": "chargefy_api_read"
}

If the connection only has the test environment, livemode does not even need to appear.

Filter by email

Each operation accepts its own filters. The assistant finds out which ones in chargefy_api_details before using them:

{
  "arguments": {
    "filters": {
      "email": "[email protected]"
    },
    "limit": 10,
    "operation": "customers.list"
  },
  "name": "chargefy_api_read"
}

A filter the operation does not know fails right away. It is not silently ignored, which keeps a wrong list from passing as a right one.

Look up by ID

{
  "arguments": {
    "id": "inv_nzaq15x9dEszxCj3",
    "operation": "invoices.get"
  },
  "name": "chargefy_api_read"
}

The result is the full object, the same as the API’s. An ID from another organization or another environment is not found.

Finding a resource without knowing the ID

Ask, for example, “find the Essential product”. For customers, catalog, discounts, links and invoices, the assistant uses the text search:

{
  "arguments": {
    "query": "essential",
    "resources": [
      "products",
      "prices"
    ]
  },
  "name": "search_chargefy_resources"
}

The search returns only a summary of each result. With the right IDs in hand, the assistant loads the full objects:

{
  "arguments": {
    "ids": [
      "prod_HtXRoNzqYjmy2pQk",
      "price_SdZX69Sm47CoNX6m"
    ]
  },
  "name": "fetch_chargefy_resources"
}

fetch_chargefy_resources is the tool for investigating: the assistant gathers up to 25 IDs that appeared in an object or in events and loads them all at once, for example to build the timeline of a payment.

Discovering before executing

When the request does not point at an obvious operation, the assistant searches the catalog:

{
  "arguments": {
    "query": "payment link",
    "risk": "R1"
  },
  "name": "chargefy_api_search"
}

And reads the contract of the chosen operation:

{
  "arguments": {
    "operation": "payment_links.create"
  },
  "name": "chargefy_api_details"
}

The input_schema in the response says which fields go into data. The link in documentation_url leads to the reference page with the product rules that do not fit in the schema.

Creating data

Create a customer

Ask:

In test, prepare a customer with the email [email protected]. Show the call and wait for my confirmation.

After you confirm:

{
  "arguments": {
    "data": {
      "email": "[email protected]",
      "metadata": {},
      "name": "Customer"
    },
    "intent_id": "9f4c1e0a-5b7d-4c2e-9a01-3d8f6b2c7e51",
    "livemode": false,
    "operation": "customers.create"
  },
  "name": "chargefy_api_create"
}

If it times out after sending, the assistant repeats exactly that call, with the same intent_id. Chargefy returns the customer that was already created instead of creating another one.

Create a link with an existing price

The assistant confirms the price exists with prices.get, reads the contract of payment_links.create and executes:

{
  "arguments": {
    "data": {
      "label": "Essential plan",
      "line_items": [
        {
          "price_id": "price_xC9prXwEQpkJghuD"
        }
      ]
    },
    "intent_id": "b6a2f8d1-77c3-4e19-a5d0-2c4e9f81b3a7",
    "livemode": false,
    "operation": "payment_links.create"
  },
  "name": "chargefy_api_create"
}

The response carries the created link and its public URL, ready to share. For a link with a one-off price, a product created on the spot or recurrence, see the variants in Create a payment link.

Updating without replacing

An update only touches the fields you send. Whatever does not appear in data stays as it was.

{
  "arguments": {
    "id": "cus_9UjeV34PYKN9Cuqb",
    "data": {
      "name": "Updated customer"
    },
    "intent_id": "e57d20c4-9b1a-4f36-8e02-6a3c1d94f7b8",
    "operation": "customers.update"
  },
  "name": "chargefy_api_update"
}

The intent_id from the creation is not valid for the update. Each change gets a new code; the same code only repeats when the same change is resent after a failure.

To clear a field’s value, you need to send it as null or empty (the input_schema says which of the two the operation accepts). Leaving the field out does not clear anything.

Planning a larger flow

For a goal that involves several resources, such as “sell a monthly plan”, the assistant can start with the planner:

{
  "arguments": {
    "context": "The customer already exists and I want to work in test only.",
    "goal": "Create a monthly product and generate a payment link"
  },
  "name": "chargefy_implementation_planner"
}

The planner returns the prerequisites, the order of the operations and the documentation pages. From there, the assistant:

confirms the plan;
discovers and details each operation;
reads existing objects;
uses a different intent_id per create or update;
validates the result of each step before moving on.

The planner only plans. It does not execute any change.

Implement white-label payments

The assistant can help build the integration in your code. Pick the path and ask it to read the full guide:

Goal	Path
A ready-made page with your brand and domain	Hosted checkout and page configuration.
A payment screen built into your product	White-label checkout with Chargefy.js.

Use get_chargefy_account_info, chargefy_api_search and chargefy_api_details to check what the connection can execute. MCP creates catalog, customers and links in the authorized organization; it looks up Checkout Sessions, setup intents and payment intents, but it does not create them or confirm payments. Those steps are implemented through the public API in your backend, with card collection by Chargefy.js in the browser. Brand and domain are configured in the Dashboard.

Chargefy for Platforms

This section only applies to Chargefy for Platforms, which operates payments for your child organizations.

Connect with a platform key. The connection then reads its own organization and, per call, one of your child organizations. Identity comes from the key; the destination travels in the request, in on_behalf_of. They are deliberately separate, the same way the public API keeps them apart (platform key + Organization header):

{
  "arguments": {
    "on_behalf_of": "org_7Dk9mQ2vX5rT8pWN",
    "operation": "payment_intents.list"
  },
  "name": "chargefy_api_read"
}

The destination is never assumed. Without on_behalf_of, the call reads the platform’s own organization — a request meant for a child is not silently answered from the platform. Find the ids with organizations.list. The link is checked on every call rather than frozen at authorization: a child that leaves the platform stops answering on the next call, with nothing to revoke by hand. And every read is recorded with the child organization actually consulted. Read-only inside child organizations. Creating or updating inside a child organization does not exist in MCP — on_behalf_of is accepted only by chargefy_api_read and chargefy_resource_fetch. A Payment Link created by MCP belongs to the organization in scope and uses its brand. To generate a payment page for a child organization with the platform’s brand, implement the API call in your backend with the platform key and the child’s Organization, following Platform brand and custom domain. In your own interface, the browser uses the platform’s publishable key and the child’s setup intent in the same environment. One environment per connection: the key is already test or live, and one connection never sees the other’s data. Create the test one first, check its reach, and only then connect the live one. Three limits surface as errors:

Attempt	Response
`on_behalf_of` on an organization connection	`platform_required`. The connection reaches only its own organization.
`on_behalf_of` with a child that is not yours, or inactive	`not_found`. An organization outside your active children answers like one that does not exist.
`on_behalf_of` on an operation that writes	The input is rejected: creating and updating inside a child is not part of MCP.

I use Chargefy for Platforms and I want to implement my own checkout with Chargefy.js for my child organizations. Read the white-label guide and the Platforms section, check the MCP permissions and implement the calls in my backend with the right key and scope. Test in sandbox and confirm payments through signed webhooks.

Investigating payments without moving money

The assistant looks up payment intents, charges, transactions, invoices, subscriptions, refunds and disputes, but it cannot act on any of them. That makes investigation safe by design. A useful request:

In the production environment and read only, look up the payment intent pi_Q3zX5Sqaeiq5n6WT. Load the related resources identified in the result and build a timeline with statuses, amounts and timestamps. Do not confirm, capture, cancel or refund anything.

Since capturing, canceling and refunding do not exist in MCP, even a badly written request cannot move money.

Paginating

Large lists come in pages. The assistant moves forward like this:

Make the first read

Choose a limit between 1 and 100. The default is 10.

Read has_more

If it is true, copy the id of the last object in data.

Fetch the next page

Repeat the operation, environment and filters with starting_after.

{
  "arguments": {
    "limit": 25,
    "operation": "customers.list",
    "starting_after": "cus_9UjeV34PYKN9Cuqb"
  },
  "name": "chargefy_api_read"
}

ending_before goes the other way. The two never go together in the same call.

Retrying

Situation	What to repeat
`rate_limited`	Wait `retry_after_ms`; keep the arguments and scope
Timeout on a read	Repeat the same call
Timeout on a write	Repeat the operation, ID, `data` and the same `intent_id`
`invalid_arguments`	Fix it according to `param` and `chargefy_api_details`
Error with `retryable: false`	Do not repeat without changing permission, context or input

Changing the intent_id after a timeout turns the retry into a second change. That is how you create a duplicate customer by accident.

Fixing common errors

Code	Cause	Next step
`no_scope`	Ambiguous environment or no active scope	Check the account and pass `livemode`; reconnect if needed
`environment_disabled`	Environment turned off for the organization	Ask an administrator to enable it
`operation_not_found`	Nonexistent `operation_id` or the wrong tool	Use `chargefy_api_search`
`operation_not_granted`	Method outside the connection’s grant	Authorize again
`write_not_allowed`	Read-only scope	Use a write scope
`missing_capability`	User without the resource’s capability	Review the user’s role
`invalid_arguments`	Invalid schema, filter, ID or `intent_id`	Compare with `chargefy_api_details`
`idempotency_key_reused`	Same `intent_id` with different parameters	Recover the original intent or generate a token for the new action
`idempotency_key_in_progress`	The same write is still processing	Wait and repeat with the same `intent_id`
`rate_limited`	Bucket exhausted	Wait `retry_after_ms`

Whenever an error comes with a request_id, keep that value. It locates the call in the dashboard’s request log and can be sent along with a report through the send_chargefy_mcp_feedback tool.

Ready-made prompts

Audit without changing

“Use Chargefy for reading only. Confirm the test environment, list open invoices and summarize amount, due date and status. Do not call chargefy_api_create or chargefy_api_update.”

Create with human review

“In test, prepare a customer with the email [email protected]. Check the schema, show data and intent_id and only execute after my confirmation.”

Investigate a failure

“Look up the request req_j8ii31CD75absd7t and whichever related objects are available. Build a timeline and preserve the request_id. Do not change any resource.”

Build a catalog and a link

“Plan selling a monthly R$ 99.90 plan in test. After my approval, create the product, the price and the link. Use a new intent_id on each write and validate each response.”

MCP

The safest way to use it

Recommended opening prompt

Querying data

List customers

Filter by email

Look up by ID

Finding a resource without knowing the ID

Discovering before executing

Creating data

Create a customer

Create a link with an existing price

Updating without replacing

Planning a larger flow

Implement white-label payments

Chargefy for Platforms

Investigating payments without moving money

Paginating

Retrying

Fixing common errors

Ready-made prompts

Keep going

Tools and operations

Limits and security

​The safest way to use it

​Recommended opening prompt

​Querying data

​List customers

​Filter by email

​Look up by ID

​Finding a resource without knowing the ID

​Discovering before executing

​Creating data

​Create a customer

​Create a link with an existing price

​Updating without replacing

​Planning a larger flow

​Implement white-label payments

​Chargefy for Platforms

​Investigating payments without moving money

​Paginating

​Retrying

​Fixing common errors

​Ready-made prompts

​Keep going

Tools and operations

Limits and security

The safest way to use it

Recommended opening prompt

Querying data

List customers

Filter by email

Look up by ID

Finding a resource without knowing the ID

Discovering before executing

Creating data

Create a customer

Create a link with an existing price

Updating without replacing

Planning a larger flow

Implement white-label payments

Chargefy for Platforms

Investigating payments without moving money

Paginating

Retrying

Fixing common errors

Ready-made prompts

Keep going