> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Limits and security
> Rate limits, risk classes, authorization boundaries, auditing and how to choose between MCP and the REST API.
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](/api-reference/introduction) 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`:
```json theme={"theme":"css-variables"}
{
"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.
## Next steps
Check the available surface and the schemas of each operation.
See flows for reading, writing, pagination and retries.