> ## 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. # Limites e segurança > Rate limits, classes de risco, fronteiras de autorização, auditoria e critérios para escolher entre o MCP e a API REST. O MCP da Chargefy foi desenhado para dar autonomia controlada a agentes. A superfície combina leitura ampla da conta com um conjunto pequeno de escritas reversíveis, sempre respeitando o acesso concedido à conexão. Esta página reúne os limites operacionais e as fronteiras de segurança que um cliente deve considerar antes de automatizar uma tarefa. ## Classes de risco Cada operação é classificada pelo impacto: | Classe | Categoria | Disponibilidade | | ------ | ------------------------------------------ | ----------------------------------- | | `R0` | Consulta de dados | Disponível | | `R1` | Escrita reversível e de baixo risco | Disponível com permissão de escrita | | `R2` | Mudança de lifecycle ou efeito financeiro | Não disponível | | `R3` | Ação administrativa ou financeira sensível | Não disponível | `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 permite `create` e `update` apenas para: * customers; * products; * prices; * discounts; * discount codes; * payment links. Não há operações `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. Para essas ações, use a [API pública](/api-reference/introduction) a partir de um backend com os controles adequados. ## 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**. | Bucket | Tools | Limite | | ------------ | ---------------------------------------------------------------------------- | ---------------------------- | | Leitura `R0` | `chargefy_api_read`, `search_chargefy_resources`, `fetch_chargefy_resources` | 120 chamadas por 60 segundos | | Escrita `R1` | `chargefy_api_write` | 30 chamadas por 60 segundos | | Descoberta | informações da conta, catálogo, documentação, planner e feedback | 240 chamadas por 60 segundos | 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ém `code: "rate_limited"`, `retryable: true` e o tempo mínimo de espera em `retry_after_ms`: ```json theme={"theme":"css-variables"} { "code": "rate_limited", "message": "Rate limit exceeded for this connection.", "retry_after_ms": 12000, "retryable": true } ``` Ao repetir: * aguarde pelo menos `retry_after_ms` e adicione jitter; * mantenha operação, `data` e `intent_id` quando a intenção de escrita for a mesma; * não crie um `intent_id` novo após timeout ou rate limit; * reduza leituras repetidas com paginação e filtros. ## Limites por chamada | Recurso | Padrão | Máximo | | ------------------------------- | ------------- | ------------- | | Lista em `chargefy_api_read` | 10 objetos | 100 objetos | | `chargefy_api_search` | 20 operações | 50 operações | | `search_chargefy_resources` | 10 resultados | 25 resultados | | `fetch_chargefy_resources` | — | 25 IDs | | `search_chargefy_documentation` | 5 resultados | 10 resultados | | Corpo da request JSON-RPC | — | 1 MB | 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ções `list` de `chargefy_api_read` usam paginação por cursor: | Argumento | Uso | | ---------------- | -------------------------------------------------------- | | `limit` | Entre 1 e 100 objetos; padrão 10 | | `starting_after` | Busca a próxima página a partir do último ID recebido | | `ending_before` | Busca a página anterior a partir do primeiro ID recebido | 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 `filters` como strings; * não use operadores arbitrários; * chaves desconhecidas retornam `invalid_arguments` com o campo em `param`; * para busca textual, prefira `search_chargefy_resources`. Quando um recorte não estiver disponível, percorra as páginas necessárias e faça o filtro no seu sistema. ## 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`, `read` ou `write`. Com apenas um ambiente autorizado, a chamada não precisa informar `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. Erros como `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 de `chargefy_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. Guarde o `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 o `intent_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. | Capacidade | Suporte | | --------------------------------- | ------- | | Streamable HTTP | Sim | | `initialize` e `ping` | Sim | | `tools/list` e `tools/call` | Sim | | Resultado com `structuredContent` | Sim | | Estado de sessão no servidor | Não | | Streaming iniciado pelo servidor | Não | | Batch JSON-RPC | Não | `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. O MCP e a API compartilham os contratos públicos. Uma investigação pode começar com o agente e virar uma automação de backend sem trocar o modelo de dados. ## Próximos passos Confira a superfície disponível e os schemas de cada operação. Veja fluxos de leitura, escrita, paginação e retry.