Skip to main content
Uma conexão MCP nunca recebe acesso genérico à conta. O alcance é formado por quatro decisões explícitas: 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: 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

​
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:
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: 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.
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

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

​
Continue

Tools e operações

Veja o catálogo completo e os argumentos de cada tool.

Exemplos de uso

Aplique o modelo de acesso em consultas e escritas seguras.