Tools e operações

Esta página é a referência técnica do MCP da Chargefy. Você não precisa dela para usar o assistente no dia a dia: ele descobre tudo isso sozinho. Ela serve para entender o que acontece por trás de cada pedido e para montar chamadas à mão quando quiser controle total. O assistente enxerga 11 ferramentas (tools) e, por meio delas, executa 63 operações. Ele trabalha em etapas: primeiro entende a conexão, depois descobre a operação certa, lê o contrato (quais campos entram e saem) e só então executa.

contexto → descoberta → contrato → leitura ou escrita

Assim a lista de ferramentas fica pequena e toda operação usa a mesma validação e devolve o mesmo objeto da API pública.

Toda conexão enxerga nove ferramentas. As duas de escrita, chargefy_api_create e chargefy_api_update, só aparecem quando pelo menos um ambiente foi autorizado com leitura e escrita.

Catálogo das 11 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_create`	Criar um recurso com idempotência
Execução	`chargefy_api_update`	Alterar um recurso existente 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`

É a primeira chamada de toda conversa e a resposta para “em que ambiente estou?”. Não recebe argumentos.

{
  "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 ambiente com environment_enabled: false aparece na lista, mas qualquer chamada nele responde environment_disabled até um administrador ligar o MCP naquele ambiente, em Developers → Agentes. Se a conexão tem teste e produção, as ferramentas que acessam dados precisam receber livemode. Com um ambiente só, o servidor já sabe qual usar.

Descoberta de operações

`chargefy_api_search`

Procura no catálogo as operações que esta conexão pode executar. É como o assistente descobre que “listar clientes” se chama customers.list.

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`

{
  "arguments": {
    "query": "link",
    "risk": "R1"
  },
  "name": "chargefy_api_search"
}

Cada resultado traz o operation_id, um resumo, o método HTTP, o caminho, a classe de risco e se a conexão pode executá-la (executable). Quando não pode, not_executable_reason explica o motivo, por exemplo “falta permissão de escrita”.

`chargefy_api_details`

Devolve o contrato completo de uma operação, ou seja, tudo que o assistente precisa saber antes de chamá-la:

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.

{
  "arguments": {
    "operation": "payment_links.create"
  },
  "name": "chargefy_api_details"
}

Um bom assistente chama chargefy_api_details antes da primeira escrita de cada operação. Os dados enviados precisam seguir exatamente o input_schema; um campo desconhecido faz a chamada falhar, em vez de ser ignorado.

Execução

`chargefy_api_read`

Executa uma operação de leitura (classe R0): listar ou consultar um recurso.

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

{
  "arguments": {
    "filters": {
      "email": "[email protected]"
    },
    "limit": 10,
    "operation": "customers.list"
  },
  "name": "chargefy_api_read"
}

starting_after e ending_before nunca vão juntos. Um filtro desconhecido ou inválido responde invalid_arguments.

`chargefy_api_create`

Cria um recurso (classe R1). Só aceita operações terminadas em .create; se receber uma .update, recusa e aponta a ferramenta certa.

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

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

Criar só adiciona, então a ferramenta é marcada como não destrutiva. Por isso, muitos assistentes executam criações sem pedir confirmação a cada chamada. Se você quiser aprovar antes, diga isso no pedido.

`chargefy_api_update`

Altera um recurso existente, indicado por id (classe R1). Só aceita operações terminadas em .update.

Argumento	Tipo	Regra
`operation`	`string`	Obrigatório; uma operação `.update`
`id`	`string`	Obrigatório; ID público do recurso alterado
`intent_id`	`string`	Obrigatório; token opaco de 16 a 64 caracteres
`data`	`object`	Obrigatório; segue o `input_schema` da operação
`livemode`	`boolean`	Necessário quando teste e ao vivo têm escrita
`organization`	`string`	Opcional; não muda a organização da conexão

{
  "arguments": {
    "id": "cus_9Kd2WqPtR7bLmA3v",
    "data": {
      "name": "Cliente Premium"
    },
    "intent_id": "1c7f4a92-8e35-4d60-bb14-27a9f0e5c3d8",
    "operation": "customers.update"
  },
  "name": "chargefy_api_update"
}

Alterar mexe em algo que já existe, então a ferramenta é marcada como destrutiva (destructiveHint). Assistentes que respeitam a marcação pedem confirmação antes de cada execução. Campos que não aparecem em data continuam com o valor atual. Nas duas ferramentas, repetir a mesma chamada com o mesmo intent_id devolve o resultado original, sem executar de novo. O mesmo intent_id com outra operação ou outros dados é recusado.

Busca e carregamento de dados

`search_chargefy_resources`

Procura um texto nos campos visíveis de cada recurso. É o que atende pedidos como “encontre o cliente da Maria”.

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.

{
  "arguments": {
    "query": "essencial",
    "resources": [
      "products",
      "prices"
    ]
  },
  "name": "search_chargefy_resources"
}

A resposta traz só um resumo de cada resultado: id, object, display_name e created_at. Para o objeto completo, o assistente usa fetch_chargefy_resources ou chargefy_api_read.

`fetch_chargefy_resources`

Carrega até 25 objetos de uma vez, a partir dos IDs. O prefixo do ID diz o tipo do recurso:

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

{
  "arguments": {
    "ids": [
      "cus_E1MR2Rb27ssEATmx",
      "inv_Px5Lh2P4zir7g6N8"
    ]
  },
  "name": "fetch_chargefy_resources"
}

IDs que não existem, que o assistente não conhece ou que ele não pode ver aparecem em missing, sem dizer qual dos três casos é. Assim, um ID de outra organização não revela nem que existe.

Apoio

`search_chargefy_documentation`

Pesquisa nesta documentação. É como o assistente responde “como valido a assinatura de um webhook?” com a página certa.

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

{
  "arguments": {
    "language": "pt",
    "query": "validar assinatura de webhook"
  },
  "name": "search_chargefy_documentation"
}

A resposta traz título, URL, idioma e um trecho curto de cada página. O conteúdo encontrado é referência para o assistente ler, não uma instrução para ele seguir.

`chargefy_implementation_planner`

Monta um plano passo a passo para um objetivo de integração, como “vender um plano mensal por link”. O plano lista pré-requisitos, operações e páginas de documentação. Ele nunca executa nada.

Em pedidos sobre ativação, o planejador diferencia a sua própria conta de uma organização conectada à sua plataforma. O MCP orienta os dois casos e lê as organizações conectadas (organizations.list e organizations.get); criar, alterar e ativar continua pela API pública. Veja Ativar organização por API ou Ativar organização por sessão hospedada.

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

{
  "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 um relato para a equipe da Chargefy sobre o próprio MCP: um erro, uma operação que falta ou uma dúvida de documentação.

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

{
  "arguments": {
    "category": "missing_capability",
    "comment": "Preciso filtrar clientes pelo documento.",
    "operation": "customers.list",
    "tool_name": "chargefy_api_read"
  },
  "name": "send_chargefy_mcp_feedback"
}

Essa ferramenta só registra o relato. Ela não altera nada na conta.

As 63 operações

São 49 leituras, 2 cálculos (prévias de fatura e de pagamento, que simulam um valor sem alterar nada e por isso rodam 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`)**	✓	✓	—	—
Planos de taxas (`fee_plans`)***	✓	✓	—	—
Preview de invoice (`invoice_previews`)	—	—	✓*	—
Preview de pagamento (`payment_previews`)	—	—	✓*	—

O nome de cada operação segue <recurso>.<ação>: invoices.list, subscriptions.get, prices.update.

Cada conexão vale para uma organização. Em contas com Chargefy for Platforms, a conexão feita na organização da plataforma também lê as organizações conectadas a ela: organizations.list e organizations.get devolvem o objeto completo, com o activation_status e a lista de pendências requirements, e os eventos organization.* aparecem em events.list. Criar, atualizar e ativar organizações conectadas continua pela API pública.

Poder consultar não significa poder agir. refunds.get lê um reembolso que já existe; refunds.create não existe no MCP.

Respostas

Quando dá certo, a ferramenta devolve:

content, o resultado em texto JSON, para assistentes que leem texto;
structuredContent, o mesmo resultado em formato estruturado;
nas operações de execução, exatamente o mesmo objeto que a API pública devolve.

Listagens usam:

{
  "object": "list",
  "data": [],
  "has_more": false,
  "url": null
}

Quando dá errado, a resposta vem com isError: true e um erro estruturado, com o código, a mensagem e o que fazer:

{
  "code": "invalid_arguments",
  "message": "Invalid data for customers.create.",
  "param": "data",
  "retryable": false,
  "suggested_action": "Check chargefy_api_details for customers.create."
}

Podem aparecer também request_id, para localizar a chamada no log, e retry_after_ms, o tempo de espera em caso de limite. Erros de protocolo (JSON-RPC) ficam reservados para mensagens malformadas ou ferramentas que não existem.

Continue

Exemplos de uso

Veja como combinar contexto, descoberta, leitura e escrita.

Limites e segurança

Consulte rate limits, auditoria e operações indisponíveis.

* O create das prévias é um cálculo: roda por chargefy_api_read com data, não exige intent_id e nunca altera dados. ** Só para contas com Chargefy for Platforms: a conexão feita na organização da plataforma lê as organizações conectadas a ela. Sem plataforma, a operação responde platform_required. *** Só para contas com Chargefy for Platforms e só na conexão feita com a API key da plataforma: ela lê os planos de taxas da própria plataforma, sem on_behalf_of. Conexões OAuth, mesmo na organização da plataforma, e conexões sem plataforma respondem permission_denied. Criar e editar planos acontece no painel.

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

Tools e operações

Catálogo das 11 tools

Contexto

`get_chargefy_account_info`

Descoberta de operações

`chargefy_api_search`

`chargefy_api_details`

Execução

`chargefy_api_read`

`chargefy_api_create`

`chargefy_api_update`

Busca e carregamento de dados

`search_chargefy_resources`

`fetch_chargefy_resources`

Apoio

`search_chargefy_documentation`

`chargefy_implementation_planner`

`send_chargefy_mcp_feedback`

As 63 operações

Respostas

Continue

Exemplos de uso

Limites e segurança

​Catálogo das 11 tools

​Contexto

​get_chargefy_account_info

​Descoberta de operações

​chargefy_api_search

​chargefy_api_details

​Execução

​chargefy_api_read

​chargefy_api_create

​chargefy_api_update

​Busca e carregamento de dados

​search_chargefy_resources

​fetch_chargefy_resources

​Apoio

​search_chargefy_documentation

​chargefy_implementation_planner

​send_chargefy_mcp_feedback

​As 63 operações

​Respostas

​Continue

Exemplos de uso

Limites e segurança

Catálogo das 11 tools

Contexto

`get_chargefy_account_info`

Descoberta de operações

`chargefy_api_search`

`chargefy_api_details`

Execução

`chargefy_api_read`

`chargefy_api_create`

`chargefy_api_update`

Busca e carregamento de dados

`search_chargefy_resources`

`fetch_chargefy_resources`

Apoio

`search_chargefy_documentation`

`chargefy_implementation_planner`

`send_chargefy_mcp_feedback`

As 63 operações

Respostas

Continue