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

# MCP da Chargefy

> Conecte um assistente à Chargefy, autorize uma organização e valide a primeira consulta em poucos minutos.

O MCP da Chargefy conecta assistentes compatíveis ao seu ambiente Chargefy. Depois da autorização, o agente pode consultar dados, encontrar documentação e executar alterações operacionais de baixo risco com as mesmas regras e os mesmos objetos públicos da API.

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

| Item         | Comportamento                                                              |
| ------------ | -------------------------------------------------------------------------- |
| Transporte   | Streamable HTTP                                                            |
| Protocolo    | MCP `2025-11-25`                                                           |
| Autenticação | OAuth ou API key de organização                                            |
| Contexto     | Uma organização por conexão; teste e ao vivo são autorizados separadamente |
| Superfície   | 10 tools de contexto, descoberta, execução, busca e apoio                  |
| Escrita      | Somente operações reversíveis de baixo risco, com idempotência             |

<Info>
  O MCP não amplia as permissões de quem se conecta. Organização, ambiente,
  leitura e escrita são limitados pelo consentimento OAuth ou pela API key e
  revalidados a cada chamada.
</Info>

## O que você pode fazer

Com uma conexão de leitura, o agente pode:

* listar e consultar 16 tipos de recurso, como clientes, produtos, invoices, cobranças, assinaturas e eventos;
* buscar clientes, itens de catálogo, links de pagamento e invoices por texto;
* carregar vários objetos pelos IDs em uma única chamada;
* pesquisar a documentação da Chargefy;
* montar um plano de integração sem executar alterações.

Com acesso de escrita, ele também pode criar e atualizar clientes, produtos, preços, descontos, códigos de desconto e links de pagamento.

<Warning>
  Capturas, confirmações, reembolsos, cancelamentos, movimentações financeiras,
  secrets e ações administrativas não fazem parte do MCP. Use a API pública e
  controles próprios no seu backend para esses fluxos.
</Warning>

## Antes de conectar

Você precisa de:

* uma conta Chargefy e acesso à organização que será conectada;
* um cliente com suporte a MCP remoto por Streamable HTTP;
* o MCP habilitado no ambiente desejado em **Desenvolvedores → Conexões**;
* OAuth pelo navegador ou uma API key **de organização**;
* acesso de escrita somente se o agente precisar criar ou editar dados.

O ambiente de **teste vem habilitado por padrão**. O ambiente **ao vivo vem desabilitado** até um administrador liberá-lo.

## Conectar com OAuth

OAuth é o caminho recomendado para uso interativo. O cliente abre a Chargefy no navegador, você escolhe uma organização e define o acesso de teste e/ou ao vivo.

<Tabs>
  <Tab title="Claude Code">
    Adicione o servidor remoto:

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

    Abra `/mcp`, selecione **chargefy** e escolha **Authenticate**. Depois do
    login, selecione uma organização e revise o acesso de cada ambiente.
  </Tab>

  <Tab title="Codex">
    Adicione o servidor e inicie o login:

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

    Ao concluir o consentimento no navegador, confirme a conexão com:

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

    O aplicativo, a CLI e a extensão do Codex compartilham a configuração MCP
    no mesmo host.
  </Tab>

  <Tab title="ChatGPT">
    No aplicativo desktop, abra **Settings → MCP servers → Add server**,
    escolha **Streamable HTTP** e informe:

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

    Salve, reinicie quando solicitado e escolha **Authenticate**. No ChatGPT
    Work pela web, servidores MCP remotos são disponibilizados por plugins e
    podem depender da política do workspace.
  </Tab>

  <Tab title="Claude / Claude Desktop">
    Abra **Settings → Connectors**, adicione um conector personalizado e use:

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

    Conclua o login e o consentimento no navegador. A disponibilidade de
    conectores personalizados pode depender do plano e, em workspaces
    corporativos, da liberação de um administrador.
  </Tab>
</Tabs>

### O que acontece no consentimento

<Steps>
  <Step title="Escolha uma organização">
    Cada conexão pertence a uma única organização. Para operar outra, crie uma
    nova conexão ou revogue e conecte novamente.
  </Step>

  <Step title="Revise os ambientes">
    Teste e ao vivo aparecem separadamente. Ambientes habilitados começam
    selecionados como somente leitura.
  </Step>

  <Step title="Conceda escrita somente quando necessário">
    Leitura e escrita é uma escolha explícita. As capacidades do seu usuário
    ainda limitam quais recursos podem ser alterados.
  </Step>

  <Step title="Autorize">
    O cliente recebe a credencial OAuth e passa a enxergar apenas as tools e
    operações permitidas para essa conexão.
  </Step>
</Steps>

## Conectar com API key

Use uma API key quando a automação precisa ficar presa a uma organização e a um ambiente. O prefixo da chave define o ambiente: `ch_test_` para teste e `ch_live_` para ao vivo.

<Warning>
  O MCP não aceita chaves de plataforma com escopo `platform_admin`. Use uma API
  key de organização com escopo `read`, `write` ou `admin`.
</Warning>

### Codex

Guarde o token em uma variável de ambiente e referencie o nome da variável:

```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 com `.mcp.json`

Crie `.mcp.json` na raiz do projeto sem colocar o token real no arquivo:

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

Cada pessoa define `CHARGEFY_MCP_TOKEN` no próprio ambiente. Se o arquivo for compartilhado, o Claude Code pedirá aprovação antes de usar o servidor do projeto.

<Tip>
  Prefira OAuth para assistentes usados por pessoas. Reserve API keys para
  clientes que precisam de um contexto fixo ou que não oferecem OAuth.
</Tip>

## Validar a conexão

Peça ao agente:

> Use a conexão Chargefy somente para leitura. Mostre a organização, os ambientes e o nível de acesso disponíveis. Depois, liste até 5 clientes no ambiente de teste. Não altere nenhum dado.

O fluxo esperado é:

<Steps>
  <Step title="Ler o contexto">
    `get_chargefy_account_info` mostra a organização, os ambientes e o acesso da
    conexão.
  </Step>

  <Step title="Descobrir a operação">
    `chargefy_api_search` encontra `customers.list`.
  </Step>

  <Step title="Executar a leitura">
    `chargefy_api_read` consulta os clientes no escopo de teste.
  </Step>
</Steps>

Uma conexão somente leitura expõe nove tools. Quando existe ao menos um ambiente habilitado com acesso de escrita, `chargefy_api_write` também aparece.

## Se algo não funcionar

<AccordionGroup>
  <Accordion title="O cliente não encontra o servidor">
    Use exatamente `https://mcp.chargefy.io`, na raiz do host, e confirme que o
    cliente suporta **Streamable HTTP**. Configurações `stdio` ou SSE não se
    conectam a esse endpoint.
  </Accordion>

  <Accordion title="O navegador não abre para autenticar">
    Abra o gerenciamento de MCP do cliente e procure **Authenticate** ou
    **Login**. No Codex, execute `codex mcp login chargefy`; no Claude Code, use
    `/mcp`.
  </Accordion>

  <Accordion title="A API key é rejeitada">
    Confirme que a chave pertence a uma organização, não expirou nem foi
    revogada e começa com `ch_test_` ou `ch_live_`. Chaves de plataforma não são
    aceitas.
  </Accordion>

  <Accordion title="A conexão funciona, mas uma operação é negada">
    A instalação terminou corretamente. Verifique ambiente habilitado, acesso de
    leitura ou escrita, capacidade do usuário e concessão da operação. Veja
    [Acesso e permissões](/mcp/authentication).
  </Accordion>

  <Accordion title="O agente está usando o ambiente errado">
    Se OAuth autorizou teste e ao vivo, peça para chamar
    `get_chargefy_account_info` e envie `livemode: false` para teste ou
    `livemode: true` para ao vivo nas tools que acessam dados.
  </Accordion>
</AccordionGroup>

## Continue

<CardGroup cols={2}>
  <Card title="Acesso e permissões" icon="key" href="/mcp/authentication">
    Entenda organização, ambientes, leitura, escrita e revogação.
  </Card>

  <Card title="Tools e operações" icon="screwdriver-wrench" href="/mcp/tools">
    Consulte as 10 tools e as 61 operações disponíveis.
  </Card>

  <Card title="Exemplos de uso" icon="message" href="/mcp/how-to-use">
    Siga fluxos práticos de descoberta, consulta e escrita segura.
  </Card>

  <Card title="Limites e segurança" icon="shield-halved" href="/mcp/limits">
    Veja rate limits, auditoria e ações fora da superfície.
  </Card>
</CardGroup>