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

# Tools e operações

> Referência das 10 tools do MCP da Chargefy, das 61 operações executáveis e dos formatos de resposta.

O MCP da Chargefy usa uma superfície progressiva: o agente primeiro entende a conexão, depois descobre o método certo, lê o contrato e só então executa.

```text theme={"theme":"css-variables"}
contexto → descoberta → contrato → leitura ou escrita
```

Essa estrutura mantém `tools/list` pequeno e permite que cada operação use o mesmo handler, validação e objeto público da API REST.

<Info>
  Nove tools aparecem em toda conexão autenticada. `chargefy_api_write` só
  aparece quando existe ao menos um ambiente habilitado com acesso de escrita.
</Info>

## Catálogo das 10 tools

| Grupo      | Tool                              | Quando usar                                             |
| ---------- | --------------------------------- | ------------------------------------------------------- |
| Contexto   | `get_chargefy_account_info`       | Ver organização, ambientes e acesso                     |
| Descoberta | `chargefy_api_search`             | Encontrar operações por texto, recurso, método ou risco |
| Descoberta | `chargefy_api_details`            | Obter o schema exato de uma operação                    |
| Execução   | `chargefy_api_read`               | Executar uma operação `GET` permitida                   |
| Execução   | `chargefy_api_write`              | Criar ou atualizar com idempotência                     |
| Dados      | `search_chargefy_resources`       | Encontrar recursos por texto livre                      |
| Dados      | `fetch_chargefy_resources`        | Carregar até 25 objetos por ID                          |
| Apoio      | `search_chargefy_documentation`   | Pesquisar a documentação da Chargefy                    |
| Apoio      | `chargefy_implementation_planner` | Montar um plano de integração sem executar              |
| Apoio      | `send_chargefy_mcp_feedback`      | Relatar problema ou capacidade ausente                  |

## Contexto

### `get_chargefy_account_info`

Chame sem argumentos no início da conversa e sempre que houver dúvida sobre o ambiente.

```json theme={"theme":"css-variables"}
{
  "arguments": {},
  "name": "get_chargefy_account_info"
}
```

A resposta informa:

* autenticação `oauth` ou `api_key`;
* nome do cliente, quando disponível;
* versão do contrato;
* organização da conexão;
* escopos de teste e/ou ao vivo;
* acesso `read` ou `write` de cada escopo;
* `environment_enabled` por escopo — se o MCP está habilitado naquele ambiente;
* usuário autenticado, no OAuth.

Um escopo com `environment_enabled: false` aparece na lista, mas qualquer execução nele responde `environment_disabled` até um administrador habilitar o MCP para o ambiente nas configurações de desenvolvedor.

Se a conexão tiver teste e ao vivo, as tools que acessam dados precisam de `livemode`. Com apenas um ambiente, o servidor infere o valor.

## Descoberta de operações

### `chargefy_api_search`

Encontra métodos executáveis para a conexão.

| Argumento                | Tipo      | Regra                                              |
| ------------------------ | --------- | -------------------------------------------------- |
| `query`                  | `string`  | Busca em ID, resumo e caminho; até 200 caracteres  |
| `resource`               | `string`  | Recurso exato, como `customers` ou `payment_links` |
| `method`                 | `string`  | `GET` ou `POST`                                    |
| `risk`                   | `string`  | `R0` para leitura ou `R1` para escrita             |
| `include_non_executable` | `boolean` | Inclui operações conhecidas mas não concedidas     |
| `limit`                  | `integer` | De 1 a 50; padrão 20                               |
| `starting_after`         | `string`  | Cursor com o último `operation_id`                 |

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "query": "link",
    "risk": "R1"
  },
  "name": "chargefy_api_search"
}
```

Cada resultado traz `operation_id`, resumo, método, caminho, classe de risco e `executable`. Quando não for executável, `not_executable_reason` explica o motivo.

### `chargefy_api_details`

Retorna o contrato completo de uma operação:

* `input_schema` e `output_schema`;
* método e caminho;
* classe de risco;
* capacidade exigida;
* ambientes permitidos;
* exigência de `intent_id`;
* estado de execução para a conexão;
* URL da referência da API.

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "operation": "payment_links.create"
  },
  "name": "chargefy_api_details"
}
```

<Tip>
  Chame `chargefy_api_details` antes da primeira escrita de cada método. O
  objeto `data` deve seguir exatamente o `input_schema`; campos desconhecidos
  são rejeitados.
</Tip>

## Execução

### `chargefy_api_read`

Executa uma operação de leitura `R0`.

| Argumento        | Tipo      | Regra                                                                |
| ---------------- | --------- | -------------------------------------------------------------------- |
| `operation`      | `string`  | Obrigatório; por exemplo `customers.list`                            |
| `id`             | `string`  | Obrigatório em operações `.get`                                      |
| `limit`          | `integer` | De 1 a 100; padrão 10 em listagens                                   |
| `starting_after` | `string`  | Próxima página                                                       |
| `ending_before`  | `string`  | Página anterior                                                      |
| `filters`        | `object`  | Filtros de igualdade descritos por `chargefy_api_details`            |
| `livemode`       | `boolean` | Necessário quando teste e ao vivo estão autorizados                  |
| `organization`   | `string`  | Opcional; normalmente omitido porque a conexão já fixa a organização |

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "filters": {
      "email": "nome@email.com"
    },
    "limit": 10,
    "operation": "customers.list"
  },
  "name": "chargefy_api_read"
}
```

Não envie `starting_after` e `ending_before` juntos. Filtros desconhecidos ou inválidos retornam `invalid_arguments`.

### `chargefy_api_write`

Executa uma operação `R1` de criação ou atualização.

| Argumento      | Tipo      | Regra                                            |
| -------------- | --------- | ------------------------------------------------ |
| `operation`    | `string`  | Obrigatório; uma operação `.create` ou `.update` |
| `intent_id`    | `string`  | Obrigatório; token opaco de 16 a 64 caracteres   |
| `data`         | `object`  | Obrigatório; segue o `input_schema` da operação  |
| `id`           | `string`  | Obrigatório em operações `.update`               |
| `livemode`     | `boolean` | Necessário quando teste e ao vivo têm escrita    |
| `organization` | `string`  | Opcional; não muda a organização da conexão      |

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "data": {
      "email": "nome@email.com",
      "name": "Cliente"
    },
    "intent_id": "9f4c1e0a-5b7d-4c2e-9a01-3d8f6b2c7e51",
    "operation": "customers.create"
  },
  "name": "chargefy_api_write"
}
```

Repetir a mesma intenção com o mesmo `intent_id` devolve o resultado original. O mesmo token com outra operação ou outro `data` é rejeitado.

## Busca e carregamento de dados

### `search_chargefy_resources`

Procura texto em campos de exibição permitidos.

| Recurso          | Campos pesquisados |
| ---------------- | ------------------ |
| `customers`      | Nome e email       |
| `products`       | Nome               |
| `prices`         | Nome               |
| `discounts`      | Nome               |
| `discount_codes` | Código             |
| `payment_links`  | Rótulo             |
| `invoices`       | Número             |

Argumentos:

* `query`: obrigatório, de 2 a 200 caracteres;
* `resources`: até 8 tipos; omita para pesquisar em todos os recursos concedidos;
* `limit`: de 1 a 25; padrão 10;
* `livemode`: necessário quando os dois ambientes estão disponíveis;
* `organization`: opcional e normalmente inferido.

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "query": "essencial",
    "resources": [
      "products",
      "prices"
    ]
  },
  "name": "search_chargefy_resources"
}
```

A resposta contém resumos com `id`, `object`, `display_name` e `created_at`. Use uma tool de leitura para obter o objeto completo.

### `fetch_chargefy_resources`

Carrega até 25 objetos públicos em uma chamada. Aceita os IDs dos 24 recursos executáveis:

| Prefixo  | Recurso             | Prefixo     | Recurso                  |
| -------- | ------------------- | ----------- | ------------------------ |
| `cus_`   | Cliente             | `pi_`       | Payment intent           |
| `prod_`  | Produto             | `ch_`       | Cobrança                 |
| `price_` | Preço               | `re_`       | Reembolso                |
| `disc_`  | Desconto            | `sub_`      | Assinatura               |
| `dcode_` | Código de desconto  | `inv_`      | Invoice                  |
| `plink_` | Link de pagamento   | `txn_`      | Transação                |
| `dp_`    | Disputa             | `evt_`      | Evento                   |
| `req_`   | Request             | `we_`       | Endpoint de webhook      |
| `pm_`    | Método de pagamento | `seti_`     | Setup intent             |
| `si_`    | Item de assinatura  | `subsched_` | Cronograma de assinatura |
| `ur_`    | Registro de uso     | `file_`     | Arquivo                  |
| `cs_`    | Checkout session    | `org_`      | Organização filha        |

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "ids": [
      "cus_E1MR2Rb27ssEATmx",
      "inv_Px5Lh2P4zir7g6N8"
    ]
  },
  "name": "fetch_chargefy_resources"
}
```

IDs inexistentes, desconhecidos ou não permitidos aparecem em `missing`; eles não revelam se o objeto existe fora do escopo.

## Apoio

### `search_chargefy_documentation`

Pesquisa o índice da documentação de desenvolvedores.

| Argumento  | Regra                              |
| ---------- | ---------------------------------- |
| `query`    | Obrigatório, de 2 a 200 caracteres |
| `language` | `pt` ou `en`                       |
| `limit`    | De 1 a 10; padrão 5                |

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "language": "pt",
    "query": "validar assinatura de webhook"
  },
  "name": "search_chargefy_documentation"
}
```

A resposta traz título, URL, idioma e um trecho curto. Conteúdo encontrado é referência, não instrução para o agente.

### `chargefy_implementation_planner`

Monta um plano determinístico para um objetivo de integração. Ele pode indicar pré-requisitos, operações e páginas da documentação, mas nunca executa tools de dados.

<Info>
  Para ativação, o planner diferencia a própria conta de uma organização filha.
  O MCP orienta os dois casos e lê organizações filhas (`organizations.list` e
  `organizations.get`); criar, alterar e ativar continua pela API pública. Veja
  também as [mudanças na integração de
  ativação](/platforms/activation-integration-changes).
</Info>

| Argumento | Regra                               |
| --------- | ----------------------------------- |
| `goal`    | Obrigatório, de 10 a 500 caracteres |
| `context` | Opcional, até 2.000 caracteres      |

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "context": "Já tenho o produto criado e quero trabalhar em teste.",
    "goal": "Criar um link para vender um plano mensal"
  },
  "name": "chargefy_implementation_planner"
}
```

### `send_chargefy_mcp_feedback`

Envia feedback sobre o próprio servidor MCP.

| Argumento    | Regra                                                   |
| ------------ | ------------------------------------------------------- |
| `category`   | `bug`, `missing_capability`, `documentation` ou `other` |
| `comment`    | Obrigatório, de 5 a 2.000 caracteres                    |
| `tool_name`  | Tool relacionada, quando houver                         |
| `operation`  | `operation_id` relacionada, quando houver               |
| `request_id` | ID retornado no erro para correlação                    |

```json theme={"theme":"css-variables"}
{
  "arguments": {
    "category": "missing_capability",
    "comment": "Preciso filtrar clientes pelo documento.",
    "operation": "customers.list",
    "tool_name": "chargefy_api_read"
  },
  "name": "send_chargefy_mcp_feedback"
}
```

Essa tool registra somente o feedback. Ela não altera recursos da conta.

## As 61 operações

A superfície executável tem **47 leituras**, **2 cálculos** (previews — POSTs que não alteram nada, executados por `chargefy_api_read` com `data`) e **12 escritas**:

| Recurso                                              | `list` | `get` | `create` | `update` |
| ---------------------------------------------------- | :----: | :---: | :------: | :------: |
| Clientes (`customers`)                               |    ✓   |   ✓   |     ✓    |     ✓    |
| Produtos (`products`)                                |    ✓   |   ✓   |     ✓    |     ✓    |
| Preços (`prices`)                                    |    ✓   |   ✓   |     ✓    |     ✓    |
| Descontos (`discounts`)                              |    ✓   |   ✓   |     ✓    |     ✓    |
| Códigos de desconto (`discount_codes`)               |    ✓   |   ✓   |     ✓    |     ✓    |
| Links de pagamento (`payment_links`)                 |    ✓   |   ✓   |     ✓    |     ✓    |
| Payment intents (`payment_intents`)                  |    ✓   |   ✓   |     —    |     —    |
| Cobranças (`charges`)                                |    ✓   |   ✓   |     —    |     —    |
| Reembolsos (`refunds`)                               |    ✓   |   ✓   |     —    |     —    |
| Assinaturas (`subscriptions`)                        |    ✓   |   ✓   |     —    |     —    |
| Invoices (`invoices`)                                |    ✓   |   ✓   |     —    |     —    |
| Transações (`transactions`)                          |    ✓   |   ✓   |     —    |     —    |
| Disputas (`disputes`)                                |    ✓   |   ✓   |     —    |     —    |
| Eventos (`events`)                                   |    ✓   |   ✓   |     —    |     —    |
| Requests (`requests`)                                |    ✓   |   ✓   |     —    |     —    |
| Endpoints de webhook (`webhook_endpoints`)           |    ✓   |   ✓   |     —    |     —    |
| Métodos de pagamento (`payment_methods`)             |    ✓   |   ✓   |     —    |     —    |
| Setup intents (`setup_intents`)                      |    ✓   |   ✓   |     —    |     —    |
| Itens de assinatura (`subscription_items`)           |    ✓   |   ✓   |     —    |     —    |
| Cronogramas (`subscription_schedules`)               |    ✓   |   ✓   |     —    |     —    |
| Registros de uso (`subscription_item_usage_records`) |    ✓   |   ✓   |     —    |     —    |
| Arquivos (`files`)                                   |    ✓   |   ✓   |     —    |     —    |
| Checkout sessions (`checkout_sessions`)              |    —   |   ✓   |     —    |     —    |
| Organizações filhas (`organizations`)\*\*            |    ✓   |   ✓   |     —    |     —    |
| Preview de invoice (`invoice_previews`)              |    —   |   —   |    ✓\*   |     —    |
| Preview de pagamento (`payment_previews`)            |    —   |   —   |    ✓\*   |     —    |

Os IDs seguem `<recurso>.<ação>`, como `invoices.list`, `subscriptions.get` e `prices.update`.

<Info>
  O MCP é vinculado a uma organização. Em contas com **Chargefy for Platforms**,
  a conexão da organização da plataforma também lê suas organizações filhas:
  `organizations.list` e `organizations.get` retornam o objeto público completo,
  incluindo `activation_status` e a lista de tarefas `requirements`, e os
  eventos `organization.*` aparecem em `events.list`. Criar, atualizar e ativar
  organizações filhas continua acontecendo pela API pública.
</Info>

<Warning>
  Uma operação de consulta não concede a ação equivalente. Por exemplo,
  `refunds.get` lê um reembolso existente; não existe `refunds.create` no MCP.
</Warning>

## Respostas

Em sucesso, a tool devolve:

* `content` textual em JSON para clientes que leem texto;
* `structuredContent` com o mesmo resultado estruturado;
* o mesmo DTO público da API REST nas operações de execução.

Listagens usam:

```json theme={"theme":"css-variables"}
{
  "object": "list",
  "data": [],
  "has_more": false,
  "url": null
}
```

Erros de execução usam `isError: true` e um conteúdo estruturado:

```json theme={"theme":"css-variables"}
{
  "code": "invalid_arguments",
  "message": "Invalid data for customers.create.",
  "param": "data",
  "retryable": false,
  "suggested_action": "Check chargefy_api_details for customers.create."
}
```

Campos adicionais podem incluir `request_id` e `retry_after_ms`. Erros de protocolo JSON-RPC são reservados para mensagens inválidas ou tools desconhecidas.

## Continue

<CardGroup cols={2}>
  <Card title="Exemplos de uso" icon="message" href="/mcp/how-to-use">
    Veja como combinar contexto, descoberta, leitura e escrita.
  </Card>

  <Card title="Limites e segurança" icon="shield-halved" href="/mcp/limits">
    Consulte rate limits, auditoria e operações indisponíveis.
  </Card>
</CardGroup>

\* `create` de previews é **cálculo** (classe compute): entra em `chargefy_api_read` com `data`, não exige `intent_id` e nunca altera dados.

\*\* Exclusivo de contas com **Chargefy for Platforms**: a conexão da organização da plataforma lê suas organizações filhas. Sem plataforma, a operação responde `platform_required`.