Access and permissions

An MCP connection never receives blanket access to the account. Its reach is made of four explicit decisions:

Layer	What it defines
Credential	Who is connecting: a user via OAuth, or an API key
Organization	The single organization the connection can reach
Environment	Test, live or both
Access	Read only, or read and write, in each environment

Beyond these layers, every operation must be granted to the connection and, under OAuth, the user must still hold access and the required capability in the organization.

Authorization is revalidated on every call. Revoking a connection, an API key, an environment or the user’s access affects the next operation, without waiting for the client’s token to expire.

Enabling per environment

An administrator controls MCP under Developers → Connections:

Environment	Initial state	Recommended use
Test	Enabled	Development, prompt validation and automations
Live	Disabled	Operating on real data, after review

Disabling an environment immediately blocks every scope pointing at it. The connection stays listed and the scope stays visible, but calls return environment_disabled.

OAuth or API key

Behavior	OAuth	Organization API key
Sign-in	Browser	Bearer token
Organization	Chosen during consent	Fixed by the key
Environments	Test, live or both	One environment, fixed by the key
Access	Set separately per environment	Derived from the key’s scope
Identity	The current user	An automation credential
Revalidation	The user’s access and capabilities	The key’s validity, environment and scope
Best for	Assistants used by people	Scripts, CI and agents with fixed context

OAuth

The client discovers authentication from https://mcp.chargefy.io and opens Chargefy’s official screen.

Choosing the organization

Every OAuth session belongs to one organization. If you belong to several, pick one during consent. To use another organization, revoke the session and connect again selecting the new one. That separation keeps a natural-language request from silently switching between accounts.

Choosing access per environment

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

No access;
Read only;
Read and write.

Enabled environments start preselected as read only. Writing requires an explicit choice. You can authorize:

test only;
live only;
test and live with different access levels.

When only one environment is in scope, the tools infer livemode. If both test and live are authorized, pass it:

{
  "livemode": false
}

Use false for test and true for live. The organization is already pinned to the connection and does not need to be repeated in normal use.

Write capabilities

Selecting “read and write” sets the ceiling of the scope. The operation still depends on the user’s current capability:

Resources	Required capability
Customers	`customer.write`
Products and prices	`product.write`
Discounts and discount codes	`discount.write`
Payment links	`payment.create`

If the capability is missing, reads keep working and the change returns missing_capability.

Granting operations

During consent, Chargefy records which operations that connection may execute. That record is what makes the agent’s exact reach explainable and auditable. If the MCP surface gains an operation after authorization, it does not slip silently into existing connections. Authorize again when you want to grant the new method.

API key

Use an organization API key when the context must be fixed and predictable.

Authorization: Bearer {{API_KEY}}

The key 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 an API-key connection needs neither organization nor livemode.

Key scopes

Scope	Behavior in MCP
`read`	Exposes reads only; the write tools do not appear
`write`	Exposes reads and the low-risk writes
`admin`	Same MCP reach as `write`; administrative actions remain unavailable

Platform keys scoped platform_admin are rejected. MCP operates one organization per connection and accepts organization keys only.

Two protections for writes

Confirmation in the client

The agent should show the operation and the data before a meaningful change when you ask for confirmation. That review belongs to the client or to workspace policy. The server does not open a new confirmation screen on every call. Writing is split into two tools so the annotation can be honest: chargefy_api_create is additive and chargefy_api_update is announced as destructive (destructiveHint), because it changes an existing record. Clients that respect the annotation ask for confirmation before each update and usually run creates without a per-call confirmation.

Idempotency with `intent_id`

Every execution through chargefy_api_create or chargefy_api_update requires an opaque intent_id of 16 to 64 characters. A UUID is a good choice.

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

Rules:

generate a fresh value for each intended change;
on a timeout or transport failure, repeat the same request with the same intent_id;
the replay returns the original result instead of executing again;
reusing the token with another operation or other data returns a conflict;
reads do not use intent_id.

Revoking or reducing access

OAuth

Under Developers → Connections, you can:

update the permissions of the session;
revoke the test or the live scope;
revoke the whole session;
reconnect to change organization or access levels.

Authorizing the same client again syncs the selection: removed environments lose access, and switching organization revokes the previous organization’s scopes.

Updating permissions

When Chargefy publishes new methods, sessions already connected keep the set you authorized — nothing is added without your approval. The session is flagged as Update available, and the Update permissions action recalculates access within what you already authorized: same organization, same environment, same access level. Before applying, you see exactly what comes in and what goes out. The same action also reduces access: methods that depend on a permission you lost leave the session, and scopes for organizations you can no longer reach are revoked. To widen the reach — another organization, another environment, or moving from read to write — reconnect and consent again.

API key

Revoke the key under Developers → API keys. Revoking the credential is the definitive cut for a token-based connection.

If a key shows up in a commit, log, screenshot, conversation or shared history, treat it as compromised. Revoke it and create another one.

Recommended practices

Start in test, read only.
Keep test and production connections separate when using API keys.
Grant writes only for the period and the client that need them.
Review the application’s name and domain before approving OAuth.
Do not put API keys in version-controlled files.
Ask for human confirmation before writes with operational impact.
Review unused connections under Developers → Connections.

Access errors

Code or situation	What it means	How to resolve
Missing or invalid token	The sign-in expired or the credential was revoked	Authenticate again or use another key
`no_scope`	There is no active scope, or the environment is ambiguous	Check `get_chargefy_account_info`; pass `livemode` if needed
`environment_disabled`	MCP is turned off for that environment	Enable the environment under Developers → Connections
`org_access_revoked`	The OAuth user lost access to the organization	Review the user’s membership or reconnect
`write_not_allowed`	The environment was authorized for reading only	Reauthorize with write access or use a suitable key
`missing_capability`	The user cannot change that kind of resource	Grant the required capability or keep the operation read-only
`operation_not_granted`	The connection was not granted that operation	Authorize again and review the scope
Unsupported key	A platform key was used	Use OAuth or an organization API key

MCP

Access and permissions

Enabling per environment

OAuth or API key

OAuth

Choosing the organization

Choosing access per environment

Write capabilities

Granting operations

API key

Key scopes

Two protections for writes

Confirmation in the client

Idempotency with `intent_id`

Revoking or reducing access

OAuth

Updating permissions

API key

Recommended practices

Access errors

Keep going

Tools and operations

Usage examples

​Enabling per environment

​OAuth or API key

​OAuth

​Choosing the organization

​Choosing access per environment

​Write capabilities

​Granting operations

​API key

​Key scopes

​Two protections for writes

​Confirmation in the client

​Idempotency with intent_id

​Revoking or reducing access

​OAuth

​Updating permissions

​API key

​Recommended practices

​Access errors

​Keep going

Tools and operations

Usage examples

Enabling per environment

OAuth or API key

OAuth

Choosing the organization

Choosing access per environment

Write capabilities

Granting operations

API key

Key scopes

Two protections for writes

Confirmation in the client

Idempotency with `intent_id`

Revoking or reducing access

OAuth

Updating permissions

API key

Recommended practices

Access errors

Keep going