Limits and security

The Chargefy MCP server is designed to give agents controlled autonomy. The surface combines broad account reads with a small set of reversible writes, always within the access granted to the connection. This page gathers the operational limits and the security boundaries a client should weigh before automating a task.

Risk classes

Every operation is classified by its impact:

Class	Category	Availability
`R0`	Data retrieval	Available
`R1`	Reversible, low-risk write	Available with write permission
`R2`	Lifecycle change or financial effect	Not available
`R3`	Sensitive administrative or financial action	Not available

chargefy_api_search and chargefy_api_details report the risk class of each operation before execution.

Available writes

MCP allows create and update only for:

customers;
products;
prices;
discounts;
discount codes;
payment links.

There are no delete operations. MCP also does not capture or cancel payments, does not create refunds, does not change the lifecycle of subscriptions or invoices, does not resolve disputes, and does not administer webhooks, API keys, members or permissions.

Retrieving a financial resource never unlocks the matching action. For example, refunds.get reads an existing refund, but there is no refunds.create on the MCP surface.

For those actions, use the public API from a backend with the appropriate controls.

Rate limits

Limits use fixed 60-second windows. Reads and writes are counted per connection + resolved scope; discovery is counted per connection.

Bucket	Tools	Limit
Read `R0`	`chargefy_api_read`, `search_chargefy_resources`, `fetch_chargefy_resources`	120 calls per 60 seconds
Write `R1`	`chargefy_api_create`, `chargefy_api_update`	30 calls per 60 seconds
Discovery	account info, catalog, documentation, planner and feedback	240 calls per 60 seconds

The buckets are independent. Hitting the read limit, for instance, does not consume the write quota. A call accepted for execution counts against the limit even when the API rejects the payload during validation. Validate the arguments before repeating it.

Response when the limit is exceeded

The result carries code: "rate_limited", retryable: true and the minimum wait in retry_after_ms:

{
  "code": "rate_limited",
  "message": "Rate limit exceeded for this connection.",
  "retry_after_ms": 12000,
  "retryable": true
}

When repeating:

wait at least retry_after_ms and add jitter;
keep the operation, data and intent_id when the write intent is the same;
do not create a new intent_id after a timeout or a rate limit;
reduce repeated reads with pagination and filters.

Per-call limits

Resource	Default	Maximum
List in `chargefy_api_read`	10 objects	100 objects
`chargefy_api_search`	20 operations	50 operations
`search_chargefy_resources`	10 results	25 results
`fetch_chargefy_resources`	—	25 IDs
`search_chargefy_documentation`	5 results	10 results
JSON-RPC request body	—	1 MB

The endpoint accepts one JSON-RPC message per request. Batching is not supported. Files, images and large collections of objects should go through the public API’s own endpoints; send MCP only the IDs it needs.

Pagination

The list operations of chargefy_api_read use cursor pagination:

Argument	Use
`limit`	Between 1 and 100 objects; defaults to 10
`starting_after`	Fetches the next page from the last ID received
`ending_before`	Fetches the previous page from the first ID received

Keep going while has_more is true. Do not send starting_after and ending_before together, and preserve the same filters, organization and environment while paging.

Read filters

chargefy_api_read accepts only the equality filters defined in the operation’s schema. Check the input_schema with chargefy_api_details before assembling the call.

send filters values as strings;
do not use arbitrary operators;
unknown keys return invalid_arguments with the field in param;
for text search, prefer search_chargefy_resources.

When a given slice is not available, page through what you need and filter in your own system.

Organization and environments

A connection belongs to a single organization. Test and live are separate authorizations inside it:

test is enabled by default;
live is disabled by default;
each environment can have none, read or write access.

With only one environment authorized, the call does not need to pass livemode. If both test and live are available, send livemode on the tools that reach data to choose the scope. An administrator can change availability under Developers → Connections. Disabling an environment blocks its use immediately and returns environment_disabled.

Authorization checks

Rate limiting and authorization are different controls. Before executing a tool, the server verifies:

that the connection is active;
that the OAuth user still has access to the organization;
that the environment is enabled;
that the requested scope was granted;
that the operation is part of that scope’s grant;
that the user or API key holds the required capability;
that the arguments match the resolved organization and environment.

Errors such as no_scope, environment_disabled, org_access_revoked, write_not_allowed, missing_capability and operation_not_granted are not solved by retrying. Adjust the connection or the permission named in the error.

Idempotent writes

Every call to chargefy_api_create and chargefy_api_update requires an intent_id between 16 and 64 characters. It identifies the intent within the connection and keeps a retry from applying the same change twice.

the same intent_id, operation and payload return the already recorded result;
reusing the token with different content returns idempotency_key_reused;
an identical execution still in flight returns idempotency_key_in_progress;
idempotency does not bypass rate limits and does not grant permissions.

Store the intent_id alongside the task that originated the write.

Auditing

Calls record the connection, the resolved scope, the operation, the risk class, the status and the duration. Writes also include the intent_id and, when available, the related object. Operations executed through the API appear in the dashboard’s request log with MCP as their origin. Use the request_id returned in errors to correlate the agent’s response with that trail. The recorded states distinguish calls that were denied, limited, in flight, completed, failed or served by an idempotent replay.

State and protocol

The server is stateless: each request is authorized and resolved without depending on the previous one. Conversation memory belongs to the client, not to the Chargefy MCP server.

Capability	Supported
Streamable HTTP	Yes
`initialize` and `ping`	Yes
`tools/list` and `tools/call`	Yes
Result with `structuredContent`	Yes
Server-side session state	No
Server-initiated streaming	No
JSON-RPC batching	No

tools/list reflects the current connection. Without write permission, chargefy_api_create and chargefy_api_update are not exposed.

Data returned to the agent

Names, descriptions, metadata and other fields coming from the account must be treated as data, never as instructions. The client should not let text stored in a resource change the agent’s policy, reveal credentials or authorize an extra action. Also avoid putting secrets, raw card data or unnecessary information into prompts and feedback.

When to use the REST API

Prefer the REST API when the integration requires:

an operation absent from chargefy_api_search;
sustained throughput above the MCP limits;
filters or expansions that do not exist in the operation’s schema;
lifecycle, money movement or an administrative action;
deterministic execution from your backend, with no agent in the decision.

MCP and the API share the same public contracts. An investigation can start with the agent and become a backend automation without changing the data model.

MCP

Limits and security

Risk classes

Available writes

Rate limits

Response when the limit is exceeded

Per-call limits

Read filters

Organization and environments

Authorization checks

Idempotent writes

Auditing

State and protocol

Data returned to the agent

When to use the REST API

Next steps

Tools and operations

Usage examples

​Risk classes

​Available writes

​Rate limits

​Response when the limit is exceeded

​Per-call limits

​Pagination

​Read filters

​Organization and environments

​Authorization checks

​Idempotent writes

​Auditing

​State and protocol

​Data returned to the agent

​When to use the REST API

​Next steps

Tools and operations

Usage examples

Risk classes

Available writes

Rate limits

Response when the limit is exceeded

Per-call limits

Pagination

Read filters

Organization and environments

Authorization checks

Idempotent writes

Auditing

State and protocol

Data returned to the agent

When to use the REST API

Next steps