Zeno

npx add-mcp 'https://app.zeno-works.ch/mcp'

Trabalhando com um assistente de IA (MCP)

Aponte o assistente de IA que você já usa para seus livros contábeis no Zeno via MCP — como conectá-lo, o que ele pode acessar e o que ele nunca pode ultrapassar.

---

O aplicativo web não é a única forma de acessar o Zeno. Se você já usa um assistente de IA — do tipo desktop ou linha de comando — você pode apontá-lo para seus livros e descrever o que deseja em suas próprias palavras, em vez de clicar pelas telas. Este capítulo aborda o que é a conexão, o que um assistente pode e não pode acessar, como configurá-la e o que isso significa para a segurança dos seus livros.

O que é MCP

MCP é uma convenção publicada que permite a um assistente de IA usar um sistema externo como ferramenta, e o Zeno fala essa linguagem. Uma vez conectados, seu assistente pode consultar informações nos seus livros e realizar trabalho neles, da mesma forma que já usa as outras ferramentas que você lhe deu. Você não precisa aprender nada sobre a convenção em si — apenas um assistente que a suporte, um endereço e uma chave.

O que um assistente pode acessar

O aplicativo web do próprio Zeno não tem porta dos fundos privada: cada tela que você usa funciona chamando a interface do Zeno, e as ferramentas oferecidas ao seu assistente são geradas a partir dessa mesma interface quando a conexão é iniciada. Nenhuma das duas superfícies é uma cópia mantida manualmente da outra, então elas não divergem, e um assistente alcança quase tudo que o aplicativo faz: leitura e lançamento dos livros, conciliação bancária, itens em aberto, faturas de fornecedores e clientes, cobrança, folha de pagamento, períodos de IVA, ativos fixos e o fechamento de exercício.

Algumas coisas são deliberadamente mantidas fora, e vale a pena nomeá-las em vez de escondê-las:

• Alguns uploads de arquivos não têm equivalente. Recibos anexados a despesas e a lançamentos de caixa registradora, o formulário de recibos de despesas por funcionário, o logotipo no seu perfil de emissor de faturas, o arquivo de importação de funcionários da folha de pagamento, uma importação de configuração completa e o arquivo de tarifas ESTV Quellensteuer só podem ser enviados pelo aplicativo. Documentos em geral são tranquilos — uma fatura de fornecedor, um recibo, um extrato bancário ou as contas anuais do ano passado entram pela mesma porta que Documentos → Caixa de entrada.
• Chaves não podem gerenciar chaves. Criar, listar ou revogar uma chave de API exige uma sessão de navegador autenticada. Um assistente que possui uma chave não pode criar outra, e isso é deliberado.

Uma coisa surpreende as pessoas. Seu assistente recebe uma lista curta de ações cotidianas, não o Zeno inteiro. Várias centenas de outras estão conectadas e podem ser chamadas, mas não estão nessa lista, e o assistente é instruído a buscar uma ação pelo nome antes de concluir que algo não é suportado. Alguns esquecem. Se o seu algum dia disser que o Zeno não pode fazer algo que você sabe que pode, peça para ele buscar a ação pelo nome.

Por que vale a pena fazer

O trabalho que o Zeno modela tem formato de fila, e uma fila é algo em que um assistente é bom. Quando documentos chegam, qualquer coisa sobre a qual o contador de IA não tinha certeza é retida em vez de lançada, e limpar essa fila no aplicativo significa abrir os itens um a um. Um assistente pode percorrer tudo e dizer o que aceitou e o que deixou para você.

O tipo de instrução que isso atende:

• “Revise as faturas de fornecedores do mês passado e me diga quais parecem erradas — alíquota de IVA errada, um fornecedor que nunca pagamos antes, um valor fora da linha com o anterior.”
• “Tudo o que o contador de IA reteve para aprovação este mês: mostre-me cada um com o documento, lance os que estão obviamente corretos e liste o restante.”

Uma chave de acesso total também cobre todas as empresas às quais você pertence, o que atende um Treuhänder que trabalha com uma carteira de clientes sem trocar de empresa para cada um.

Seja claro sobre o que não muda. Seu papel governa um assistente exatamente como governa você na tela: ele pode fazer o que você pode fazer naquela empresa, e nada mais. O que ele não passa é Configurações → Autonomia, que decide quanto o contador de IA pode lançar sem supervisão a partir de documentos que chegam no Zeno — não o que um assistente externo pode lançar. Um lançamento que um assistente faz é feito quando ele o faz, então se ele verifica com você antes é um hábito do seu cliente e não um controle do Zeno. Tampouco um backlog inteiro viaja por aqui: os documentos passam pelo assistente um a um, bom para um punhado e inútil para um ano de papelada. Para um backlog, conecte uma caixa de correio ou uma pasta em Configurações → Integrações, ou solte os arquivos em Documentos → Caixa de entrada, e deixe o assistente trabalhar a fila que isso produz.

Configurando

Qualquer cliente compatível com MCP serve, desde que possa adicionar um servidor HTTP e definir um cabeçalho de requisição. Um cliente que não pode definir cabeçalhos não pode enviar sua chave de forma alguma — veja o último item de solução de problemas.

Configurações da conta → Chaves de API: cada chave com seu escopo, seu prefixo público, quando foi usada pela última vez e Revogar.

1. Abra o menu do usuário na parte inferior da barra lateral → Configurações da conta → Chaves de API e escolha Criar chave de API.
2. Dê a ela um Nome que você reconhecerá depois — nomeie-a conforme o assistente que você está conectando.
3. Escolha um Escopo. As opções são Acesso total — todas as suas empresas, que “age com seu acesso total à conta em todas as empresas às quais você pertence”, ou uma de suas empresas pelo nome, que é “confinado a esta única empresa, com seu papel nela”. Escolha uma única empresa, a menos que tenha um motivo para não fazer isso.
4. Defina uma Expiração se quiser. O padrão é nunca, e o conselho da própria tela vale a pena seguir: “Prefira uma expiração para uma chave que você cola em um agente de IA ou ferramenta de terceiros.”
5. Copie o segredo agora. Ele é mostrado uma única vez, imediatamente após a criação, e nunca mais. O Zeno mantém apenas um hash dele.
6. Nas configurações de conexão do seu assistente, adicione um servidor HTTP. O endereço é seu endereço web comum do Zeno com /mcp no final. Envie a chave como um cabeçalho chamado X-API-Key; clientes que só oferecem token de portador podem colocar a chave lá em vez disso.

A maioria dos clientes aceita uma lista de servidores neste formato:

{
  "mcpServers": {
    "zeno": {
      "type": "http",
      "url": "https://your-zeno-address/mcp",
      "headers": {
        "X-API-Key": "paste-your-key-here"
      }
    }
  }
}

Algumas instalações também oferecem aprovação no navegador em vez de uma chave colada: você adiciona o endereço sem credencial, o Zeno envia você para uma página para aprovar, e o token chega ao cliente sem nunca aparecer na conversa. Se isso está ativado pertence à sua instalação do Zeno, não ao assistente, então pergunte a quem administra a sua. Onde estiver desativado, a chave é o caminho de entrada.

Verificando se funcionou

A chave é verificada apenas quando o assistente realmente faz algo, então um cliente relatando “conectado” não diz nada sobre se ele pode agir. Prove pedindo algo que precise dos seus dados: “liste minhas empresas” ou “qual é minha liquidez?”. Uma resposta correta significa que o endereço, a chave e seu acesso estão todos alinhados.

Segurança e controle

• Uma chave nunca excede seu próprio acesso. O Zeno a resolve de volta para você, e cada porta de papel e empresa se aplica exatamente como no navegador. Um assistente conectado com a chave de um membro pode ler, mas não pode lançar — lançar exige o papel de contador ou proprietário.
• Um escopo de empresa única é um limite real. Uma chave confinada à empresa A é recusada na empresa B, mesmo uma à qual você pertença. A tela não oferece escopo mais fino do que esses dois, e o escopo apenas estreita seu acesso, nunca o amplia — uma chave de acesso total “pode fazer tudo que sua conta pode, em todas as empresas às quais você pertence. Trate-a como sua senha.”
• O que ela faz é feito de verdade. Não há sandbox, nem modo de teste, nem simulação. Um lançamento que seu assistente faz é um lançamento nos seus livros, sob seu nome na trilha de auditoria. Correções são estornos lançados a prazo, como em qualquer outro lugar no razão geral.
• O trabalho é marcado como trabalho de máquina. Um lançamento feito por esta conexão carrega a origem MCP, que Contabilidade → Diário mostra no lançamento e filtra, para que você possa ver depois quais lançamentos uma máquina decidiu.
• Revogar corta o acesso imediatamente. Use Revogar na linha da chave: “Qualquer script que use esta chave parará de funcionar imediatamente. Isso não pode ser desfeito.” Revogar interrompe chamadas futuras; não reverte nada já lançado. Chaves não podem ser recuperadas — crie uma nova.
• O que o Zeno armazena. O Prefixo público, para que você possa distinguir chaves, e o segredo apenas como hash. Último uso registra quando uma requisição autenticou pela última vez com ela. A conexão não mantém nada entre requisições: seu assistente envia a chave a cada vez.

Diga claramente a si mesmo antes de colar uma chave em qualquer lugar: um assistente que a possui pode agir nos seus livros. Limite-a a uma empresa, dê uma expiração, revogue-a quando o trabalho estiver concluído.

Como isso se relaciona com o contador de IA

O contador de IA já está dentro do aplicativo e não precisa de nada disso. Um cliente externo é uma segunda forma de entrada.

O contador de IA que você conheceu em Introdução já está conectado e não precisa de chave. Ele é o mais restrito dos dois por design: ele lê texto de documentos que qualquer pessoa pode enviar por e-mail para sua empresa, então seu alcance é deliberadamente limitado. Um assistente externo, autenticado com uma chave que você provisionou, tem alcance de escrita mais amplo. Nenhum substitui o outro, e Configurações → Autonomia governa apenas o primeiro — quanto o contador de IA pode lançar sem supervisão. Um assistente externo é limitado pelo seu papel. Veja Configurações e integrações.

Se algo der errado

• Uma mensagem sobre chave de API ausente. O cliente não enviou chave, ou enviou sob um nome de cabeçalho diferente de X-API-Key ou um token de portador. Lembre-se de que a conexão é bem-sucedida sem uma; é a primeira chamada de ferramenta que falha.
• “Não autorizado”, ou uma recusa em uma empresa, mas não em outra. Ou a chave está revogada ou expirada, ou está com escopo de empresa e o assistente tentou acessar uma empresa diferente. Expirar e revogar dão mensagens diferentes, porque os remédios diferem.
• Uma recusa que menciona seu papel. Lançar, registrar pagamentos e aceitar trabalho retido exigem o papel de contador ou proprietário naquela empresa. A chave não pode elevar isso.
• O cliente conecta, mas não oferece nenhuma ação do Zeno. Ele nunca alcançou o servidor — verifique se o endereço termina em /mcp antes de suspeitar da chave.
• O assistente diz que um recurso não existe. Peça para ele buscar a ação pelo nome. A lista cotidiana é curta de propósito; a maior parte do Zeno está atrás dessa busca.
• Adicionar o Zeno a partir de um conector que não pode definir cabeçalhos não faz nada. Alguns conectores autenticam apenas no navegador e não podem enviar uma chave de forma alguma. Use um cliente que permita definir um cabeçalho, ou uma instalação com aprovação no navegador ativada.