Tools e operações

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.

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.

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

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.

{
  "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`

{
  "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.

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

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.

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

{
  "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

{
  "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.

{
  "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

{
  "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

{
  "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.

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.

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

{
  "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.

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.

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.

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:

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

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

{
  "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

Exemplos de uso

Veja como combinar contexto, descoberta, leitura e escrita.

Limites e segurança

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

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

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Tools e operações

Catálogo das 10 tools

Contexto

`get_chargefy_account_info`

Descoberta de operações

`chargefy_api_search`

`chargefy_api_details`

Execução

`chargefy_api_read`

`chargefy_api_write`

Busca e carregamento de dados

`search_chargefy_resources`

`fetch_chargefy_resources`

Apoio

`search_chargefy_documentation`

`chargefy_implementation_planner`

`send_chargefy_mcp_feedback`

As 61 operações

Respostas

Continue

Exemplos de uso

Limites e segurança

​Catálogo das 10 tools

​Contexto

​get_chargefy_account_info

​Descoberta de operações

​chargefy_api_search

​chargefy_api_details

​Execução

​chargefy_api_read

​chargefy_api_write

​Busca e carregamento de dados

​search_chargefy_resources

​fetch_chargefy_resources

​Apoio

​search_chargefy_documentation

​chargefy_implementation_planner

​send_chargefy_mcp_feedback

​As 61 operações

​Respostas

​Continue

Exemplos de uso

Limites e segurança

Catálogo das 10 tools

Contexto

`get_chargefy_account_info`

Descoberta de operações

`chargefy_api_search`

`chargefy_api_details`

Execução

`chargefy_api_read`

`chargefy_api_write`

Busca e carregamento de dados

`search_chargefy_resources`

`fetch_chargefy_resources`

Apoio

`search_chargefy_documentation`

`chargefy_implementation_planner`

`send_chargefy_mcp_feedback`

As 61 operações

Respostas

Continue