> ## 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.

# Chargefy MCP

> Connect an assistant to Chargefy, authorize an organization and validate your first query in minutes.

The Chargefy MCP server connects compatible assistants to your Chargefy environment. Once authorized, the agent can query data, find documentation and run low-risk operational changes under the same rules and the same public objects as the API.

```text theme={"theme":"css-variables"}
https://mcp.chargefy.io
```

| Item           | Behavior                                                                 |
| -------------- | ------------------------------------------------------------------------ |
| Transport      | Streamable HTTP                                                          |
| Protocol       | MCP `2025-11-25`                                                         |
| Authentication | OAuth or an organization API key                                         |
| Context        | One organization per connection; test and live are authorized separately |
| Surface        | 11 tools for context, discovery, execution, search and support           |
| Writes         | Reversible low-risk operations only, with idempotency                    |

<Info>
  MCP never widens the permissions of whoever connects. Organization,
  environment, read and write are bounded by the OAuth consent or by the API key
  and revalidated on every call.
</Info>

## What you can do

With a read connection, the agent can:

* list and retrieve 16 resource types, such as customers, products, invoices, charges, subscriptions and events;
* search customers, catalog items, payment links and invoices by text;
* load several objects by ID in a single call;
* search the Chargefy documentation;
* draft an integration plan without executing any change.

With write access, it can also create and update customers, products, prices, discounts, discount codes and payment links.

<Warning>
  Captures, confirmations, refunds, cancellations, money movement, secrets and
  administrative actions are not part of MCP. Use the public API and your own
  backend controls for those flows.
</Warning>

## Before you connect

You need:

* a Chargefy account and access to the organization you want to connect;
* a client that supports remote MCP over Streamable HTTP;
* MCP enabled for the environment you want, under **Developers → Connections**;
* OAuth in the browser or an **organization** API key;
* write access only if the agent needs to create or edit data.

The **test environment is enabled by default**. The **live environment starts disabled** until an administrator turns it on.

## Connect with OAuth

OAuth is the recommended path for interactive use. The client opens Chargefy in the browser, you pick an organization and set the access level for test and/or live.

<Tabs>
  <Tab title="Claude Code">
    Add the remote server:

    ```bash theme={"theme":"css-variables"}
    claude mcp add --transport http chargefy https://mcp.chargefy.io
    ```

    Open `/mcp`, select **chargefy** and choose **Authenticate**. After signing
    in, pick an organization and review the access for each environment.
  </Tab>

  <Tab title="Codex">
    Add the server and start the login:

    ```bash theme={"theme":"css-variables"}
    codex mcp add chargefy --url https://mcp.chargefy.io
    codex mcp login chargefy
    ```

    Once you finish the consent in the browser, confirm the connection with:

    ```bash theme={"theme":"css-variables"}
    codex mcp list
    ```

    The Codex app, CLI and extension share the same MCP configuration on the
    same host.
  </Tab>

  <Tab title="ChatGPT">
    In the desktop app, open **Settings → MCP servers → Add server**, choose
    **Streamable HTTP** and enter:

    ```text theme={"theme":"css-variables"}
    https://mcp.chargefy.io
    ```

    Save, restart when prompted and choose **Authenticate**. On ChatGPT Work for
    web, remote MCP servers are delivered through plugins and may depend on
    workspace policy.
  </Tab>

  <Tab title="Claude / Claude Desktop">
    Open **Settings → Connectors**, add a custom connector and use:

    ```text theme={"theme":"css-variables"}
    https://mcp.chargefy.io
    ```

    Complete the sign-in and consent in the browser. Custom connector
    availability may depend on your plan and, in enterprise workspaces, on an
    administrator enabling it.
  </Tab>
</Tabs>

### What happens during consent

<Steps>
  <Step title="Pick an organization">
    Every connection belongs to a single organization. To work in another one,
    create a new connection or revoke and connect again.
  </Step>

  <Step title="Review the environments">
    Test and live appear separately. Enabled environments start selected as read
    only.
  </Step>

  <Step title="Grant writes only when needed">
    Read and write is an explicit choice. Your user's own capabilities still
    bound which resources can be changed.
  </Step>

  <Step title="Authorize">
    The client receives the OAuth credential and from then on sees only the
    tools and operations allowed for that connection.
  </Step>
</Steps>

## Connect with an API key

Use an API key when an automation must stay pinned to one organization and one environment. The key prefix defines the environment: `ch_test_` for test and `ch_live_` for live.

<Warning>
  MCP does not accept platform keys scoped as `platform_admin`. Use an
  organization API key scoped `read`, `write` or `admin`.
</Warning>

### Codex

Keep the token in an environment variable and reference the variable name:

```bash theme={"theme":"css-variables"}
export CHARGEFY_MCP_TOKEN="{{API_KEY}}"
codex mcp add \
  --url https://mcp.chargefy.io \
  --bearer-token-env-var CHARGEFY_MCP_TOKEN \
  chargefy
```

### Claude Code with `.mcp.json`

Create `.mcp.json` at the project root without putting the real token in the file:

```jsonc theme={"theme":"css-variables"}
{
  "mcpServers": {
    "chargefy": {
      "headers": {
        "Authorization": "Bearer ${CHARGEFY_MCP_TOKEN}"
      },
      "type": "http",
      "url": "https://mcp.chargefy.io"
    }
  }
}
```

Each person sets `CHARGEFY_MCP_TOKEN` in their own environment. If the file is shared, Claude Code asks for approval before using the project server.

<Tip>
  Prefer OAuth for assistants used by people. Reserve API keys for clients that
  need a fixed context or that do not offer OAuth.
</Tip>

## Validate the connection

Ask the agent:

> Use the Chargefy connection for reading only. Show the organization, the environments and the access level available. Then list up to 5 customers in the test environment. Do not change any data.

The expected flow is:

<Steps>
  <Step title="Read the context">
    `get_chargefy_account_info` shows the organization, the environments and the
    connection's access.
  </Step>

  <Step title="Discover the operation">
    `chargefy_api_search` finds `customers.list`.
  </Step>

  <Step title="Execute the read">
    `chargefy_api_read` queries customers in the test scope.
  </Step>
</Steps>

A read-only connection exposes nine tools. When at least one enabled environment has write access, `chargefy_api_create` and `chargefy_api_update` show up as well.

## If something does not work

<AccordionGroup>
  <Accordion title="The client cannot find the server">
    Use exactly `https://mcp.chargefy.io`, at the host root, and confirm the
    client supports **Streamable HTTP**. `stdio` or SSE configurations do not
    connect to this endpoint.
  </Accordion>

  <Accordion title="The browser does not open to authenticate">
    Open the client's MCP management screen and look for **Authenticate** or
    **Login**. On Codex, run `codex mcp login chargefy`; on Claude Code, use
    `/mcp`.
  </Accordion>

  <Accordion title="The API key is rejected">
    Confirm the key belongs to an organization, has not expired or been revoked
    and starts with `ch_test_` or `ch_live_`. Platform keys are not accepted.
  </Accordion>

  <Accordion title="The connection works, but an operation is denied">
    The installation finished correctly. Check the enabled environment, read or
    write access, the user's capability and the operation grant. See [Access and
    permissions](/en/mcp/authentication).
  </Accordion>

  <Accordion title="The agent is using the wrong environment">
    If OAuth authorized both test and live, ask it to call
    `get_chargefy_account_info` and send `livemode: false` for test or
    `livemode: true` for live on the tools that reach data.
  </Accordion>
</AccordionGroup>

## Keep going

<CardGroup cols={2}>
  <Card title="Access and permissions" icon="key" href="/en/mcp/authentication">
    Understand organization, environments, read, write and revocation.
  </Card>

  <Card title="Tools and operations" icon="screwdriver-wrench" href="/en/mcp/tools">
    Browse the 11 tools and the 61 available operations.
  </Card>

  <Card title="Usage examples" icon="message" href="/en/mcp/how-to-use">
    Follow practical flows for discovery, querying and safe writes.
  </Card>

  <Card title="Limits and security" icon="shield-halved" href="/en/mcp/limits">
    See rate limits, auditing and actions outside the surface.
  </Card>
</CardGroup>