Tools and operations

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.

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.

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.

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.

{
  "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`

{
  "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.

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

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

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

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

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

{
  "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.

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

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

{
  "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.

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 or the hosted activation session.

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

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

{
  "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.

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.

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

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:

{
  "object": "list",
  "data": [],
  "has_more": false,
  "url": null
}

Execution errors use isError: true and a structured payload:

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

Usage examples

See how to combine context, discovery, reads and writes.

Limits and security

Check rate limits, auditing and unavailable operations.

* 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.

​Catalog of the 11 tools

​Context

​get_chargefy_account_info

​Operation discovery

​chargefy_api_search

​chargefy_api_details

​Execution

​chargefy_api_read

​chargefy_api_create

​chargefy_api_update

​Searching and loading data

​search_chargefy_resources

​fetch_chargefy_resources

​Support

​search_chargefy_documentation

​chargefy_implementation_planner

​send_chargefy_mcp_feedback

​The 61 operations

​Responses

​Keep going

Usage examples

Limits and security

Catalog of the 11 tools

Context

`get_chargefy_account_info`

Operation discovery

`chargefy_api_search`

`chargefy_api_details`

Execution

`chargefy_api_read`

`chargefy_api_create`

`chargefy_api_update`

Searching and loading data

`search_chargefy_resources`

`fetch_chargefy_resources`

Support

`search_chargefy_documentation`

`chargefy_implementation_planner`

`send_chargefy_mcp_feedback`

The 61 operations

Responses

Keep going