> ## 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. # Acesso e permissões > Entenda como organização, ambiente, leitura, escrita e credencial limitam cada conexão MCP. Uma conexão MCP nunca recebe acesso genérico à conta. O alcance é formado por quatro decisões explícitas: | Camada | O que define | | ----------- | ----------------------------------------------------- | | Credencial | Quem está se conectando: usuário por OAuth ou API key | | Organização | A única organização que a conexão pode acessar | | Ambiente | Teste, ao vivo ou ambos | | Acesso | Somente leitura ou leitura e escrita em cada ambiente | Além dessas camadas, cada operação precisa estar concedida à conexão e, no OAuth, o usuário precisa continuar com acesso e com a capacidade exigida na organização. A autorização é revalidada em toda chamada. Revogar uma conexão, uma API key, um ambiente ou o acesso do usuário afeta a próxima operação, sem depender da expiração do token no cliente. ## Habilitação por ambiente Um administrador controla o MCP em **Desenvolvedores → Conexões**: | Ambiente | Estado inicial | Uso recomendado | | -------- | -------------- | -------------------------------------------------- | | Teste | Habilitado | Desenvolvimento, validação de prompts e automações | | Ao vivo | Desabilitado | Operação com dados reais após revisão | Desabilitar um ambiente bloqueia imediatamente todos os escopos que apontam para ele. A conexão continua listada e o escopo continua visível, mas as chamadas retornam `environment_disabled`. ## OAuth ou API key | Comportamento | OAuth | API key de organização | | ------------- | ----------------------------------- | --------------------------------------- | | Login | Navegador | Bearer token | | Organização | Escolhida no consentimento | Fixada pela chave | | Ambientes | Teste, ao vivo ou ambos | Um ambiente, fixado pela chave | | Acesso | Definido separadamente por ambiente | Derivado do escopo da chave | | Identidade | Usuário atual | Credencial de automação | | Revalidação | Acesso e capacidades do usuário | Validade, ambiente e escopo da chave | | Melhor uso | Assistentes usados por pessoas | Scripts, CI e agentes com contexto fixo | ## OAuth O cliente descobre a autenticação a partir de `https://mcp.chargefy.io` e abre a tela oficial da Chargefy. ### Escolher a organização Cada sessão OAuth pertence a **uma organização**. Se você participa de várias, escolha uma no consentimento. Para usar outra organização, revogue a sessão e conecte novamente selecionando a nova. Essa separação evita que um pedido em linguagem natural alterne silenciosamente entre contas. ### Escolher o acesso por ambiente Para a organização selecionada, cada ambiente habilitado oferece três opções: * **Sem acesso**; * **Somente leitura**; * **Leitura e escrita**. Ambientes habilitados começam pré-selecionados como **somente leitura**. Escrita exige uma escolha explícita. Você pode autorizar: * somente teste; * somente ao vivo; * teste e ao vivo com níveis de acesso diferentes. Quando só existe um ambiente no escopo, as tools inferem `livemode`. Se teste e ao vivo estiverem autorizados, informe: ```json theme={"theme":"css-variables"} { "livemode": false } ``` Use `false` para teste e `true` para ao vivo. A organização já está fixada na conexão e não precisa ser repetida no uso normal. ### Capacidades de escrita Selecionar “leitura e escrita” define o teto do escopo. A operação ainda depende da capacidade atual do usuário: | Recursos | Capacidade exigida | | ------------------------------- | ------------------ | | Clientes | `customer.write` | | Produtos e preços | `product.write` | | Descontos e códigos de desconto | `discount.write` | | Links de pagamento | `payment.create` | Se a capacidade faltar, leituras continuam disponíveis e a alteração retorna `missing_capability`. ### Concessão de operações No consentimento, a Chargefy registra quais operações aquela conexão pode executar. Esse registro permite explicar e auditar o alcance exato do agente. Se a superfície MCP ganhar uma operação depois da autorização, ela não entra silenciosamente em conexões existentes. Autorize novamente quando precisar conceder o novo método. ## API key Use uma API key de organização quando o contexto precisa ser fixo e previsível. ```text theme={"theme":"css-variables"} Authorization: Bearer {{API_KEY}} ``` A chave define: * a organização; * o ambiente pelo prefixo `ch_test_` ou `ch_live_`; * o alcance `read`, `write` ou `admin`; * expiração e revogação. Por isso, uma conexão por API key não precisa de `organization` nem de `livemode`. ### Escopos da chave | Escopo | Comportamento no MCP | | ------- | --------------------------------------------------------------------------------- | | `read` | Expõe somente leitura; `chargefy_api_write` não aparece | | `write` | Expõe leitura e as escritas de baixo risco | | `admin` | Tem o mesmo alcance MCP de `write`; ações administrativas continuam indisponíveis | Chaves de plataforma com `platform_admin` são rejeitadas. O MCP opera uma organização por conexão e aceita somente chaves de organização. ## Duas proteções para escrita ### Confirmação no cliente O agente deve mostrar a operação e os dados antes de uma alteração relevante quando você pedir confirmação. Essa revisão pertence ao cliente ou à política do workspace. O servidor não abre uma nova tela de confirmação em cada chamada. ### Idempotência com `intent_id` Toda execução por `chargefy_api_write` exige um `intent_id` opaco de 16 a 64 caracteres. Um UUID é uma boa opção. ```json theme={"theme":"css-variables"} { "arguments": { "data": { "email": "nome@email.com" }, "intent_id": "9f4c1e0a-5b7d-4c2e-9a01-3d8f6b2c7e51", "operation": "customers.create" }, "name": "chargefy_api_write" } ``` Regras: * gere um valor novo para cada intenção de alteração; * em timeout ou falha de transporte, repita o mesmo pedido com o mesmo `intent_id`; * o replay devolve o resultado original em vez de executar novamente; * reutilizar o token com outra operação ou outros dados retorna conflito; * leituras não usam `intent_id`. ## Revogar ou reduzir acesso ### OAuth Em **Desenvolvedores → Conexões**, você pode: * **atualizar as permissões** da sessão; * revogar o escopo de teste ou ao vivo; * revogar a sessão inteira; * reconectar para mudar organização ou níveis de acesso. Autorizar novamente o mesmo cliente sincroniza a seleção: ambientes removidos deixam de ter acesso e uma troca de organização revoga os escopos da organização anterior. #### Atualizar permissões Quando a Chargefy publica métodos novos, as sessões já conectadas continuam com o conjunto que você autorizou — nada é adicionado sem o seu aval. A sessão aparece marcada como **Atualização disponível**, e a ação **Atualizar permissões** recalcula o acesso dentro do que você já autorizou: mesma organização, mesmo ambiente e mesmo nível de acesso. Antes de aplicar, você vê exatamente o que entra e o que sai. A mesma ação também **reduz** acesso: métodos que dependem de uma permissão que você perdeu saem da sessão, e escopos de organizações que você não alcança mais são revogados. Para ampliar o alcance — outra organização, outro ambiente ou passar de leitura para escrita — continue reconectando e consentindo de novo. ### API key Revogue a chave em **Desenvolvedores → Chaves de API**. Revogar a credencial é o corte definitivo para uma conexão por token. Se uma chave aparecer em commit, log, screenshot, conversa ou histórico compartilhado, considere-a comprometida. Revogue-a e crie outra. ## Práticas recomendadas * Comece em teste e somente leitura. * Separe conexões de teste e produção quando usar API key. * Conceda escrita apenas para o período e o cliente necessários. * Revise o nome e o domínio do aplicativo antes de aprovar OAuth. * Não coloque API keys em arquivos versionados. * Peça confirmação humana antes de escritas com impacto operacional. * Revise conexões sem uso em **Desenvolvedores → Conexões**. ## Erros de acesso | Código ou situação | Significado | Como resolver | | ------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- | | Token ausente ou inválido | Login expirou ou credencial foi revogada | Autentique novamente ou use outra chave | | `no_scope` | Não existe escopo ativo ou o ambiente não foi identificado | Consulte `get_chargefy_account_info`; informe `livemode` se necessário | | `environment_disabled` | O MCP está desligado naquele ambiente | Habilite o ambiente em **Desenvolvedores → Conexões** | | `org_access_revoked` | O usuário OAuth perdeu acesso à organização | Revise a participação do usuário ou reconecte | | `write_not_allowed` | O ambiente foi autorizado somente para leitura | Reautorize com escrita ou use uma chave adequada | | `missing_capability` | O usuário não pode alterar aquele tipo de recurso | Conceda a capacidade necessária ou mantenha a operação em leitura | | `operation_not_granted` | A conexão não recebeu aquela operação | Autorize novamente e revise o escopo | | Chave não suportada | Foi usada uma chave de plataforma | Use OAuth ou uma API key de organização | ## Continue Veja o catálogo completo e os argumentos de cada tool. Aplique o modelo de acesso em consultas e escritas seguras.