Classes de risco
Cada operação é classificada pelo impacto:chargefy_api_search e chargefy_api_details informam a classe de risco de
cada operação antes da execução.
Escritas disponíveis
O MCP permitecreate e update apenas para:
- customers;
- products;
- prices;
- discounts;
- discount codes;
- payment links.
delete. O MCP também não captura ou cancela pagamentos, não
cria reembolsos, não muda o lifecycle de subscriptions ou invoices, não resolve
disputas e não administra webhooks, API keys, membros ou permissões.
Consultar um recurso financeiro não libera a ação correspondente. Por exemplo,
refunds.get lê um reembolso existente, mas não existe refunds.create na
superfície MCP.Rate limits
Os limites usam janelas fixas de 60 segundos. Leituras e escritas são contadas por conexão + escopo resolvido; descoberta é contada por conexão.
Os buckets são independentes. Atingir o limite de leitura, por exemplo, não
consome a cota de escrita.
Uma chamada aceita para execução conta no limite mesmo quando a API rejeita o
payload por validação. Valide os argumentos antes de repetir.
Resposta ao exceder o limite
O resultado contémcode: "rate_limited", retryable: true e o tempo mínimo
de espera em retry_after_ms:
- aguarde pelo menos
retry_after_mse adicione jitter; - mantenha operação,
dataeintent_idquando a intenção de escrita for a mesma; - não crie um
intent_idnovo após timeout ou rate limit; - reduza leituras repetidas com paginação e filtros.
Limites por chamada
O endpoint aceita uma mensagem JSON-RPC por request. Batch não é suportado.
Arquivos, imagens e grandes coleções de objetos devem seguir pelos endpoints
próprios da API pública; envie ao MCP apenas os IDs necessários.
Paginação
As operaçõeslist de chargefy_api_read usam paginação por cursor:
Continue enquanto
has_more for true. Não envie starting_after e
ending_before juntos e preserve os mesmos filtros, organização e ambiente
durante a navegação.
Filtros de leitura
chargefy_api_read aceita apenas os filtros de igualdade definidos no schema
da operação. Consulte o input_schema com chargefy_api_details antes de
montar a chamada.
- envie os valores de
filterscomo strings; - não use operadores arbitrários;
- chaves desconhecidas retornam
invalid_argumentscom o campo emparam; - para busca textual, prefira
search_chargefy_resources.
Organização e ambientes
Uma conexão pertence a uma única organização. Teste e ao vivo são autorizações separadas dentro dela:- teste é habilitado por padrão;
- ao vivo é desabilitado por padrão;
- cada ambiente pode ter acesso
none,readouwrite.
livemode. Se teste e ao vivo estiverem disponíveis, envie livemode nas
tools que acessam dados para escolher o escopo.
Um administrador pode mudar a disponibilidade em Desenvolvedores →
Conexões. Desabilitar um ambiente bloqueia seu uso imediatamente e retorna
environment_disabled.
Verificações de autorização
Rate limit e autorização são controles diferentes. Antes de executar uma tool, o servidor verifica:- se a conexão está ativa;
- se o usuário OAuth ainda acessa a organização;
- se o ambiente está habilitado;
- se o escopo solicitado foi concedido;
- se a operação faz parte do grant daquele escopo;
- se o usuário ou a API key tem a capacidade necessária;
- se os argumentos correspondem à organização e ao ambiente resolvidos.
no_scope, environment_disabled, org_access_revoked,
write_not_allowed, missing_capability e operation_not_granted não são
resolvidos por retry. Ajuste a conexão ou a permissão indicada.
Escritas idempotentes
Toda chamada dechargefy_api_write exige um intent_id entre 16 e 64
caracteres. Ele identifica a intenção dentro da conexão e evita que um retry
aplique a mesma alteração duas vezes.
- o mesmo
intent_id, operação e payload devolvem o resultado já registrado; - reutilizar o token com conteúdo diferente retorna
idempotency_key_reused; - uma execução igual ainda em andamento retorna
idempotency_key_in_progress; - idempotência não ignora rate limits nem concede permissões.
intent_id junto da tarefa que originou a escrita.
Auditoria
As chamadas registram conexão, escopo resolvido, operação, classe de risco, status e duração. Escritas também incluem ointent_id e, quando disponível,
o objeto relacionado.
As operações executadas pela API aparecem no log de requests do dashboard com
origem MCP. Use o request_id retornado em erros para correlacionar a resposta
do agente com essa trilha.
Os estados registrados distinguem chamadas negadas, limitadas, em andamento,
concluídas, com falha ou atendidas por replay idempotente.
Estado e protocolo
O servidor é stateless: cada request é autorizada e resolvida sem depender da request anterior. A memória da conversa pertence ao cliente, não ao MCP da Chargefy.tools/list reflete a conexão atual. Sem permissão de escrita,
chargefy_api_write não é exposta.
Dados retornados ao agente
Nomes, descrições, metadata e outros campos vindos da conta devem ser tratados como dados, nunca como instruções. O cliente não deve permitir que texto salvo em um recurso altere a política do agente, revele credenciais ou autorize uma ação adicional. Também evite colocar secrets, dados brutos de cartão ou informações desnecessárias em prompts e feedbacks.Quando usar a API REST
Prefira a API REST quando a integração exige:- uma operação ausente de
chargefy_api_search; - throughput sustentado acima dos limites do MCP;
- filtros ou expansões que não existem no schema da operação;
- lifecycle, movimentação financeira ou ação administrativa;
- execução determinística pelo seu backend, sem decisão de um agente.
Próximos passos
Tools e operações
Confira a superfície disponível e os schemas de cada operação.
Exemplos de uso
Veja fluxos de leitura, escrita, paginação e retry.