Tools and operations

This page is the technical reference for the Chargefy MCP. You do not need it to use the assistant day to day: it discovers all of this on its own. It is here to help you understand what happens behind each request and to build calls by hand when you want full control. The assistant sees 11 tools and, through them, executes 63 operations. It works in stages: first it understands the connection, then it discovers the right operation, reads the contract (which fields go in and come out) and only then executes.

context → discovery → contract → read or write

That way the tool list stays small and every operation uses the same validation and returns the same object as the public API.

Every connection sees nine tools. The two write tools, chargefy_api_create and chargefy_api_update, only appear when at least one environment was authorized with read and 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`

It is the first call of every conversation and the answer to “which environment am I in?”. It takes no arguments.

{
  "arguments": {},
  "name": "get_chargefy_account_info"
}

The response tells you:

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

An environment with environment_enabled: false appears in the list, but any call in it answers environment_disabled until an administrator turns MCP on for that environment, under Developers → Agents. If the connection has test and production, the tools that access data need to receive livemode. With a single environment, the server already knows which one to use.

Operation discovery

`chargefy_api_search`

Searches the catalog for the operations this connection can execute. It is how the assistant discovers that “list customers” is called customers.list.

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 the operation_id, a summary, the HTTP method, the path, the risk class and whether the connection can execute it (executable). When it cannot, not_executable_reason explains why, for example “write permission missing”.

`chargefy_api_details`

Returns the full contract of an operation, that is, everything the assistant needs to know before calling it:

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

A good assistant calls chargefy_api_details before the first write of each operation. The data sent must follow the input_schema exactly; an unknown field makes the call fail instead of being ignored.

Execution

`chargefy_api_read`

Executes a read operation (class R0): listing or looking up a resource.

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 production are authorized
`organization`	`string`	Optional; usually omitted because the connection already pins the organization

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

starting_after and ending_before never go together. An unknown or invalid filter answers invalid_arguments.

`chargefy_api_create`

Creates a resource (class R1). It only accepts operations ending in .create; if it receives an .update, it refuses and points 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 production have write access
`organization`	`string`	Optional; does not change the connection’s organization

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

Creating only adds, so the tool is marked as non-destructive. That is why many assistants run creates without asking for confirmation on every call. If you want to approve first, say so in your request.

`chargefy_api_update`

Changes an existing resource, identified by id (class R1). It only accepts operations 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 production 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 touches something that already exists, so the tool is marked as destructive (destructiveHint). Assistants that respect the marking ask for confirmation before each execution. Fields that do not appear in data keep their current value. On both tools, repeating the same call with the same intent_id returns the original result, without executing again. The same intent_id with another operation or other data is refused.

Searching and loading data

`search_chargefy_resources`

Searches for a text in the visible fields of each resource. It is what handles requests like “find Maria’s customer record”.

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 only a summary of each result: id, object, display_name and created_at. For the full object, the assistant uses fetch_chargefy_resources or chargefy_api_read.

`fetch_chargefy_resources`

Loads up to 25 objects at once, from their IDs. The ID prefix tells the resource type:

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, that the assistant does not know or that it is not allowed to see show up under missing, without saying which of the three it is. That way, an ID from another organization does not even reveal that it exists.

Support

`search_chargefy_documentation`

Searches this documentation. It is how the assistant answers “how do I verify a webhook signature?” with the right page.

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 the title, URL, language and a short excerpt of each page. The content found is reference material for the assistant to read, not an instruction for it to follow.

`chargefy_implementation_planner`

Builds a step-by-step plan for an integration goal, such as “sell a monthly plan through a link”. The plan lists prerequisites, operations and documentation pages. It never executes anything.

In requests about activation, the planner distinguishes your own account from an organization connected to your platform. MCP guides both cases and reads connected organizations (organizations.list and organizations.get); creating, changing and activating them still goes through the public API. See Activate an organization by API or Activate an organization with a hosted 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 a report to the Chargefy team about MCP itself: a bug, a missing operation or a documentation question.

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 report. It does not change anything in the account.

The 63 operations

They are 49 reads, 2 calculations (invoice and payment previews, which simulate an amount without changing anything and therefore run 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`)**	✓	✓	—	—
Fee plans (`fee_plans`)***	✓	✓	—	—
Invoice preview (`invoice_previews`)	—	—	✓*	—
Payment preview (`payment_previews`)	—	—	✓*	—

Each operation’s name follows <resource>.<action>: invoices.list, subscriptions.get, prices.update.

Each connection is valid for one organization. On accounts with Chargefy for Platforms, the connection made in the platform organization also reads the organizations connected to it: organizations.list and organizations.get return the full object, with the activation_status and the requirements list of pending items, and organization.* events show up in events.list. Creating, updating and activating connected organizations still goes through the public API.

Being able to look something up does not mean being able to act on it. refunds.get reads a refund that already exists; refunds.create does not exist in MCP.

Responses

When it succeeds, the tool returns:

content, the result as JSON text, for assistants that read text;
structuredContent, the same result in structured form;
on execution operations, exactly the same object the public API returns.

Lists use:

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

When it fails, the response comes with isError: true and a structured error, with the code, the message and what to do:

{
  "code": "invalid_arguments",
  "message": "Invalid data for customers.create.",
  "param": "data",
  "retryable": false,
  "suggested_action": "Check chargefy_api_details for customers.create."
}

request_id, to locate the call in the log, and retry_after_ms, the wait time when a limit is hit, may appear as well. Protocol errors (JSON-RPC) are reserved for malformed messages or tools that do not exist.

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: it runs through chargefy_api_read with data, requires no intent_id and never changes data. ** Only for accounts with Chargefy for Platforms: the connection made in the platform organization reads the organizations connected to it. Without a platform, the operation answers platform_required. *** Only for accounts with Chargefy for Platforms, and only on the connection made with the platform’s API key: it reads the platform’s own fee plans, without on_behalf_of. OAuth connections, even in the platform organization, and connections without a platform answer permission_denied. Plans are created and edited in the dashboard.

​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 63 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 63 operations

Responses

Keep going