Usage examples

You can talk in natural language; the client assembles the MCP calls. The examples below show the JSON only to make each decision verifiable.

The safest pattern

Read the context

Call get_chargefy_account_info and confirm organization, environment and access.

Discover the operation

Use chargefy_api_search instead of guessing the operation_id.

Read the contract

Check chargefy_api_details, especially before a write.

Verify the current state

Read the resource or find the right ID before changing anything.

Write with confirmation and idempotency

Show the operation, data, ID and environment; then use a fresh intent_id.

Human confirmation is a client policy or an instruction of yours. The server validates scope, capability, schema and idempotency, but it does not open a confirmation screen on every write. Writing is split into chargefy_api_create (additive) and chargefy_api_update (announced as destructive), so clients that respect the annotation ask for confirmation before each update.

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 prompt avoids three common mistakes: an implicit environment, a guessed operation and a change without review.

Querying data

List customers

Ask:

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

After confirming the context, the read call can be:

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

If the connection only holds test, livemode can be omitted.

Filter by email

Filters belong to the operation. Check chargefy_api_details before using them:

{
  "arguments": {
    "filters": {
      "email": "name@email.com"
    },
    "limit": 10,
    "operation": "customers.list"
  },
  "name": "chargefy_api_read"
}

Unknown keys are rejected; they are not silently ignored.

Retrieve by ID

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

The result is the full public object. An ID from another organization or environment is not returned.

Finding a resource without knowing the ID

Use the text search for customers, catalog, discounts, links and invoices:

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

The search returns summaries. Once you have the right IDs, load the full objects:

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

fetch_chargefy_resources is useful for investigating relationships: gather up to 25 IDs found in objects or events and load them all in one call.

Discovering before executing

When the goal does not yet point at a clear operation, search:

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

Then read the contract of the one you picked:

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

Use the returned input_schema to build data. The reference at documentation_url explains product rules that do not fit in a schema.

Creating data

Create a customer

Ask:

In test, prepare a customer with the email name@email.com. Show the call and wait for my confirmation.

After the confirmation:

{
  "arguments": {
    "data": {
      "email": "name@email.com",
      "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, repeat exactly that call with the same intent_id.

Create a link with an existing price

After confirming the price with prices.get, read the details of payment_links.create and execute:

{
  "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 includes the payment_link object and its public URL. For an ad-hoc price, an inline product or recurrence, follow the variants in Create a payment link.

Updating without replacing

Updates merge: absent fields stay as they are.

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

Do not reuse the intent_id from the creation. Each logical change gets a fresh token; the token only repeats when retrying that same change.

To clear a field, confirm in the input_schema whether it accepts null or an empty string. Omitting a field does not remove it.

Planning a larger flow

For a goal spanning several resources, 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 points at prerequisites, the order of operations and the documentation. Then:

confirm the plan;
discover and detail each operation;
read existing objects;
use a different intent_id for each create or update;
validate the result of each step before moving on.

The planner never executes a change on its own.

Investigating payments without moving money

MCP can query payment intents, charges, transactions, invoices, subscriptions, refunds and disputes. A useful prompt:

In the live environment and read only, retrieve 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.

Financial lifecycle operations do not exist on the MCP surface, so investigation stays separate from action.

Paginating

Lists use a cursor:

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"
}

Use ending_before to go back. Never send both cursors together.

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 same `intent_id`
`invalid_arguments`	Fix it per `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 can turn the retry into a second change.

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`

Keep the request_id whenever it appears. It correlates the failure with Chargefy’s request log and can be sent through send_chargefy_mcp_feedback.

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 name@email.com. Check the schema, show data and intent_id, and only execute after my confirmation.”

Investigate a failure

“Retrieve 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 fresh intent_id on each write and validate every response.”

MCP

The safest pattern

Recommended opening prompt

Querying data

List customers

Filter by email

Retrieve 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

Investigating payments without moving money

Paginating

Retrying

Fixing common errors

Ready-made prompts

Keep going

Tools and operations

Limits and security

​The safest pattern

​Recommended opening prompt

​Querying data

​List customers

​Filter by email

​Retrieve 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

​Investigating payments without moving money

​Paginating

​Retrying

​Fixing common errors

​Ready-made prompts

​Keep going

Tools and operations

Limits and security

The safest pattern

Recommended opening prompt

Querying data

List customers

Filter by email

Retrieve 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

Investigating payments without moving money

Paginating

Retrying

Fixing common errors

Ready-made prompts

Keep going