MCP (Model Context Protocol)

Conecte assistentes de IA como Claude Desktop e Cursor para operar sua conta Agnozys diretamente.

O MCP da Agnozys conecta agentes de IA — Claude Desktop, Claude Code, Cursor e outros clientes compatíveis — aos dados reais da sua organização: consultar clientes, cobranças, assinaturas e notas fiscais em linguagem natural. Toda consulta respeita as mesmas permissões da sua credencial e o isolamento entre organizações da plataforma.

URL do servidor

https://mcp.agnozys.com/mcp

A autenticação é feita via OAuth 2.1. Ao adicionar o servidor, seu cliente MCP abre o navegador para que você autorize o acesso com sua conta Agnozys.

Configurar no cliente

Claude Desktop

Abra o menu Claude → Settings → Developer e clique em Edit Config. Adicione o servidor no JSON de configuração:

claude_desktop_config.json

{
  "mcpServers": {
    "agnozys": {
      "url": "https://mcp.agnozys.com/mcp"
    }
  }
}

Reinicie o Claude Desktop. Na primeira chamada, ele vai abrir o navegador para o consentimento OAuth — faça login na Agnozys e autorize o acesso.

Cursor

Vá em Settings → MCP e adicione um novo servidor:

https://mcp.agnozys.com/mcp

O Cursor vai detectar o OAuth automaticamente e redirecionar para o consentimento na Agnozys.

Claude Code

Adicione ao .mcp.json do seu projeto:

.mcp.json

{
  "mcpServers": {
    "agnozys": {
      "url": "https://mcp.agnozys.com/mcp"
    }
  }
}

Ou passe como flag na CLI:

claude --mcp-config '{"agnozys":{"url":"https://mcp.agnozys.com/mcp"}}'

Outros clientes

Qualquer cliente compatível com MCP e OAuth 2.1 funciona. O servidor expõe os metadados de descoberta em /.well-known/oauth-authorization-server — o cliente detecta o fluxo de autorização sozinho.

Depois de conectar

Uma vez autorizado, o agente de IA tem acesso às ferramentas da Agnozys dentro do escopo da sua organização e das suas permissões.

Ferramentas disponíveis

Ferramenta	O que faz
`agnozys_query_entities`	Consulta genérica de clientes, cobranças, pagamentos, assinaturas e notas fiscais, com filtros, ordenação e paginação
`agnozys_describe_entities`	Dicionário do schema: campos de cada entidade, o que significam, unidades e valores válidos de cada status
`agnozys_customers_list`	Lista clientes com busca e filtros
`agnozys_customers_get`	Detalhes de um cliente pelo ID
`agnozys_charges_list`	Lista cobranças por status, cliente ou período
`agnozys_charges_get`	Detalhes de uma cobrança pelo ID
`agnozys_charges_get_documents`	Código PIX, linha digitável e PDF do boleto como recurso tipado, binário limitado e link de fallback
`agnozys_charges_verify_status`	Confere se uma cobrança bate com o provedor (Asaas/Stark) e, com `apply`, corrige divergência
`agnozys_invoices_get_documents`	PDF, XML e XML de cancelamento como recursos tipados, binários limitados e links de fallback
`agnozys_invoices_verify_status`	Confere se uma nota foi cancelada/autorizada de verdade no provedor fiscal
`agnozys_invoices_list`	Lista notas por cliente, cobrança, status, tipo e período
`agnozys_invoices_get`	Abre os detalhes de uma nota pelo `invoiceId`
`agnozys_customers_create`	Cadastra um cliente novo — exige a sua confirmação
`agnozys_customers_update`	Altera os dados de um cliente — exige a sua confirmação
`agnozys_charges_create`	Cria cobrança PIX/boleto/cartão — confirmação; usa a credencial ativa da org
`agnozys_charges_cancel`	Cancela cobrança pendente — confirmação
`agnozys_invoices_emit`	Emite NFS-e (PENDING → worker) — devolve `invoiceId`; acompanhe com `invoices_verify_status`
`agnozys_invoices_cancel`	Cancela nota EMITTED — confirmação; motivo opcional (sem motivo, o sistema envia justificativa padrão)
`agnozys_ping`	Testa a conexão e informa o ambiente da credencial

A lista que o seu cliente enxerga é filtrada pelas permissões da credencial: uma conexão sem invoices:read, por exemplo, não consegue consultar notas fiscais e recebe um erro explicando qual permissão falta. Ferramentas de cadastro exigem customers:write. Cobrança e nota exigem charges:write / invoices:write e usam a credencial ativa da organização (sandbox ou produção). Owner ou admin da organização. Toda escrita pede confirmação antes de executar.

Documentos como assets

Quando PDF ou XML estiver disponível, as ferramentas de documentos retornam um resource_link com nome e tipo de arquivo e tentam incluir o mesmo documento como recurso MCP binário embutido. O binário é lido apenas do proxy Agnozys, sem redirecionamento, com MIME validado e limite de 8 MiB; falhas preservam o link e o JSON estruturado como fallback. Cada cliente decide se exibe esse recurso como anexo, download ou card; a Agnozys nunca devolve URL de provedor.

Nada é gravado sem você autorizar

As ferramentas que alteram dados nunca executam na primeira chamada. O agente recebe de volta um resumo do que aconteceria — no cadastro, os dados do cliente que será criado; na alteração, o valor atual ao lado do novo, campo a campo — e precisa mostrar isso para você. Só depois que você autoriza é que a operação roda. Mudar qualquer dado depois do resumo invalida a autorização e gera um resumo novo, para você ver o que mudou.

Essa etapa acontece no servidor da Agnozys, não no seu cliente de IA: conectar por um aplicativo que não pede confirmação não pula o passo.

Cadastro sem endereço não emite nota

Ao cadastrar um cliente, informe CEP, rua, cidade e UF. Sem o endereço completo o perfil fiscal não é criado e esse cliente não consegue receber nota fiscal. O resumo de confirmação avisa quando esse é o caso.

Por isso, informar inscrição estadual ou municipal exige o endereço completo: sem perfil fiscal elas não teriam onde ser gravadas, e o cadastro é recusado em vez de aceitar o dado e descartá-lo.

Se o cliente já existe sem perfil fiscal, alterar o endereço depois não cria um — o resumo de confirmação diz isso explicitamente quando acontece.

Dica: comece pelo dicionário

Peça ao agente que consulte agnozys_describe_entities antes da primeira pergunta sobre os seus dados. Ele passa a conhecer os campos exatos, os valores válidos de cada status e as unidades — o que evita respostas erradas por chute de nome de campo. Um bom primeiro pedido:

Descreva quais dados da minha conta Agnozys você consegue consultar,
depois me mostre as cobranças vencidas deste mês.

Gerenciar conexões

Para revogar o acesso de um cliente, acesse Configurações → Integrações no app Agnozys e remova a conexão na seção Apps conectados via MCP. A revogação é imediata — tokens e consentimento são invalidados na hora.

On this page