Access and permissions

A connected assistant never receives general access to your account. Four answers define its reach:

Question	What defines it
Who is connecting?	Your account (sign-in) or an API key
In which organization?	Only one per connection
In which environment?	Test, production or both
At which level?	Read only, or read and write, set per environment

On top of that, every operation must have been granted to the connection. And, when you sign in with your account, the person must still have access to the organization and the permission the operation requires.

All of this is checked again on every call. If you revoke a connection, a key, an environment or a team member’s access, the next call is already blocked. It does not depend on the token expiring in the assistant.

Enabling per environment

An administrator turns MCP on and off under Developers → Agents, one environment at a time:

Environment	How it starts	What it is for
Test	On	Developing, testing prompts and automations
Production	Off	Operating on real data, after reviewing the usage

Turning an environment off immediately blocks every connection pointing at it. The connection stays listed, but calls start answering environment_disabled.

What changes	Sign in with your account	Organization API key
How it gets in	Through the browser	With the key in the call header
Organization	Chosen on the authorization screen	Pinned by the key
Environments	Test, production or both	Only one, set by the key prefix
Access level	Chosen per environment	Comes from the key’s scope
Who answers for it	The person who signed in	The automation that owns the key
What is checked	The person’s access and permissions	The key’s validity, environment and scope
Best for	Assistants used by people	Scripts, CI and bots with a fixed context

The assistant discovers the authentication from https://mcp.chargefy.io and opens Chargefy’s official screen in the browser.

Choosing the organization

Each connection is valid for one organization. If you belong to several, you choose one on the authorization screen. To use another, revoke the connection and connect again. This rule exists so that a plain-English request never switches accounts without you noticing. “List the customers” always means that organization’s customers.

Choosing the level per environment

For the chosen organization, each enabled environment offers three options:

No access;
Read only;
Read and write.

Enabled environments come preselected as read only. Write access is an explicit choice of yours. You can, for example, grant read and write in test and read only in production. When the connection has a single environment, the assistant already knows which one to use. When it has both, it needs to say on every call:

{
  "livemode": false
}

false is test, true is production. The organization is already pinned to the connection and does not need to be passed.

What the assistant can change

Checking “read and write” sets the ceiling. Within it, the assistant only changes what your user can change in the dashboard:

Resources	Permission required from the user
Customers	`customer.write`
Products and prices	`product.write`
Discounts and discount codes	`discount.write`
Payment links	`payment.create`

If the permission is missing, reads keep working and the change answers missing_capability.

Granted operations

On the authorization screen, Chargefy records exactly which operations that connection can execute. That record is what makes it possible to explain and audit what the assistant can reach. If Chargefy publishes a new operation later, it does not slip into existing connections on its own. You update the permissions or authorize again whenever you want to grant the new method.

API key

Use an organization API key when the context needs to be fixed and predictable, as in a script or a CI routine.

Authorization: Bearer {{API_KEY}}

The key already defines:

the organization;
the environment, through the ch_test_ or ch_live_ prefix;
the reach: read, write or admin;
expiry and revocation.

That is why a key-based connection does not need to pass organization or livemode.

Key scopes

Scope	What it unlocks in MCP
`read`	Read only. The write tools do not even appear to the assistant
`write`	Reads and the low-risk writes
`admin`	Same as `write`. Administrative actions stay outside MCP

Platform keys (platform_admin scope) are refused. MCP operates one organization per connection and accepts organization keys only.

Two protections for writes

Confirmation before changing

Human confirmation happens in the assistant, not on Chargefy’s server. If you ask “show me before executing”, the assistant shows the operation and the data and waits for your go-ahead. To help the assistant decide when to ask, writing is split into two tools: chargefy_api_create, which only adds, and chargefy_api_update, which changes something that already exists and is therefore marked as destructive. Assistants that respect that marking ask for confirmation before each update and usually create without asking on every call.

Protection against duplicate changes

Every create or update requires an intent_id: a unique code of 16 to 64 characters, generated by the assistant, that identifies that intended change. A UUID works.

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

How it works:

each new change gets a new intent_id;
if the call fails because of a timeout or a dropped connection, the assistant repeats it with the same intent_id;
the repeat returns the original result, instead of creating the customer again;
using the same intent_id with another operation or other data causes a conflict;
reads do not use intent_id.

Revoking or reducing access

Connections made with your account

Under Developers → Agents, you can:

update the permissions of a connection;
revoke only the test environment or only production;
revoke the whole connection;
connect again to change organization or level.

If you authorize the same assistant again, the new selection replaces the old one: unchecked environments lose access and switching organization revokes access to the previous one.

Updating permissions

When Chargefy publishes new operations, existing connections keep only what you authorized. The connection shows up marked as Update available, and the Update permissions action recalculates the access within what you already granted: same organization, same environment, same level. Before applying, you see what comes in and what goes out. The same action also reduces access: operations that depend on a permission you lost leave the connection, and organizations you can no longer reach are revoked. To widen it (another organization, another environment or moving from read to write), connect again.

API key

Revoke the key under Developers → API keys. Revoking the key cuts the connection off for good.

If a key shows up in a commit, log, screenshot, conversation or shared history, assume it has leaked. Revoke it and create another one.

Good practices

Start in test and read only.
With API keys, use one connection for test and another for production.
Grant write access only for as long as needed, and only to the assistant that needs it.
Before authorizing, check the application’s name and domain on the authorization screen.
Never put API keys in version-controlled files.
Ask for confirmation before changes that affect your operation.
Review unused connections under Developers → Agents.

Access errors

Code or situation	What it means	How to fix it
Missing or invalid token	The sign-in expired or the credential was revoked	Sign in again or use another key
`no_scope`	There is no active access, or the environment was not specified	Call `get_chargefy_account_info`; pass `livemode` if there are two
`environment_disabled`	MCP is turned off in that environment	Turn the environment on under Developers → Agents
`org_access_revoked`	The person who connected lost access to the organization	Review their membership or connect with another account
`write_not_allowed`	The environment was authorized for reading only	Authorize again with write access, or use a key with the `write` scope
`missing_capability`	The user cannot change that kind of resource	Grant the permission in the dashboard or keep the operation read-only
`operation_not_granted`	The connection was not granted that operation	Update the permissions or authorize again
Unsupported key	A platform key was used	Sign in with your account or use an organization key

MCP

Access and permissions

Enabling per environment

Choosing the organization

Choosing the level per environment

What the assistant can change

Granted operations

API key

Key scopes

Two protections for writes

Confirmation before changing

Protection against duplicate changes

Revoking or reducing access

Connections made with your account

Updating permissions

API key

Good practices

Access errors

Keep going

Tools and operations

Usage examples

​Enabling per environment

​Sign in with your account or API key

​Sign in with your account

​Choosing the organization

​Choosing the level per environment

​What the assistant can change

​Granted operations

​API key

​Key scopes

​Two protections for writes

​Confirmation before changing

​Protection against duplicate changes

​Revoking or reducing access

​Connections made with your account

​Updating permissions

​API key

​Good practices

​Access errors

​Keep going

Tools and operations

Usage examples

Enabling per environment

Sign in with your account or API key

Sign in with your account

Choosing the organization

Choosing the level per environment

What the assistant can change

Granted operations

API key

Key scopes

Two protections for writes

Confirmation before changing

Protection against duplicate changes

Revoking or reducing access

Connections made with your account

Updating permissions

API key

Good practices

Access errors

Keep going