Skip to main content
MCP is an open standard that lets an AI assistant use tools from other systems. With the Chargefy MCP, you connect the assistant you already use (Claude, ChatGPT, Cursor, Codex and others) to your account and talk to it the way you would talk to a teammate:
How many new customers came in this month in the test environment?
Find invoice number 1042 and tell me why it is still open.
Create a R$ 99.90 payment link for the Essential plan, in test.
The assistant turns each request into calls to Chargefy, with the same rules and the same data as the public API. There is a single server address:
The assistant never gets more access than the person who connected it. It is limited to one organization, to the environments you authorize (test or production) and to the level you choose (read only, or read and write). That authorization is checked again on every request.

​
What the assistant can do

With read access, it can:
  • list and look up customers, products, prices, invoices, charges, subscriptions, transactions, refunds, disputes, events and other resources, 16 types in total;
  • search by text: “Maria’s customer record”, “the Essential product”, “invoice 1042”;
  • load several objects at once by their IDs, for example to build the timeline of a payment;
  • search this documentation;
  • draft a step-by-step integration plan without executing anything.
With write access, it can also create and edit customers, products, prices, discounts, discount codes and payment links.
Nothing that touches money goes through MCP: capturing or canceling a payment, refunding, canceling a subscription, resolving a dispute, managing keys, webhooks or team members. For those, keep using the public API from your backend, with whatever controls you define.

​
Before you connect

You need:
  • a Chargefy account with access to the organization you are going to connect;
  • an assistant that supports remote MCP servers. Claude, ChatGPT, Cursor and Codex do;
  • MCP enabled for the environment you want, under Developers → Agents. The test environment comes enabled; production stays off until an administrator turns it on.
To develop with Claude Code, Codex, or Cursor, start with Code with AI agents: it covers skill installation and the MCP connection. If you already installed the Claude Code plugin, the server comes configured; you only need to authorize your account.

​
Connect with your account

This is the usual path for anyone who is going to chat with the assistant. You add the server, the browser opens the Chargefy sign-in screen and you choose what the assistant can access. Technically, it is an OAuth sign-in.
Add the remote server:
Type /mcp, select chargefy and choose Authenticate. After signing in, select an organization and set the access for each environment.

​
The authorization screen

1

Choose an organization

Each connection is valid for a single organization. If you belong to several, choose one. To use another one later, revoke and connect again.
2

Set the access per environment

Test and production appear separately. Enabled environments come preselected as read only.
3

Grant write access only if you need it

Checking “read and write” is your choice. Even with write access, the assistant only changes what your user can change in the dashboard.
4

Authorize

Done. From then on, the assistant sees only the tools allowed for that connection.

​
Connect with an API key

Use an API key when whoever is connecting is not a person but a script, a CI bot or an automation. The key already pins the organization and the environment: ch_test_ is test, ch_live_ is production.
Platform keys (platform_admin scope) do not work with MCP. Use an organization key with the read, write or admin scope.

​
Codex

Store the key in an environment variable and pass only the variable name:

​
Claude Code with .mcp.json

Create a .mcp.json file at the project root. The real key does not go into the file, only the variable name:
Each person on the team sets CHARGEFY_MCP_TOKEN on their own computer. If the file is shared in the repository, Claude Code asks for approval before using the server.
For assistants used by people, prefer signing in with your account. Leave the API key for automations or for clients that do not offer sign-in.

​
Test the connection

Ask the assistant:
Use the Chargefy connection for reading only. Show the organization, the environments and the access level. Then list up to 5 customers in the test environment. Do not change anything.
Behind the scenes, it makes three calls:
1

Reads the context

get_chargefy_account_info says which organization, which environments and which access level the connection has.
2

Discovers the operation

chargefy_api_search finds customers.list.
3

Runs the read

chargefy_api_read lists the test customers.
If the response comes back with the customers, everything is working. A read-only connection shows the assistant nine tools. When any environment has write access, two more appear: chargefy_api_create and chargefy_api_update.

​
If something does not work

Use exactly https://mcp.chargefy.io, with nothing after the slash, and confirm that the assistant supports Streamable HTTP. stdio or SSE configurations do not connect to this address.
Open the assistant’s MCP management screen and look for Authenticate or Login. On Codex, run codex mcp login chargefy; on Claude Code, type /mcp.
Check that the key belongs to an organization (not a platform), that it starts with ch_test_ or ch_live_ and that it has not expired or been revoked.
The installation is fine; the problem is permission. Check whether the environment is enabled, whether the connection has read or write access, whether your user has the required capability and whether the operation was granted. See Access and permissions.
If you authorized both test and production, ask it to call get_chargefy_account_info and to pass livemode: false (test) or livemode: true (production) on the calls that access data.

​
Keep going

Access and permissions

Understand organization, environments, read, write and revocation.

Tools and operations

Browse the 11 tools and the 63 available operations.

Usage examples

Follow practical flows for discovery, querying and safe writes.

Limits and security

See rate limits, auditing and actions outside MCP.