This MCP server connects Claude to the Sienge ERP (construction/real-estate), handling diagnostics, authentication, and — after loading modules — purchase and supply-contract workflows in Portuguese.
Core capabilities (available immediately): test connection (testar_conexao), check which auth method is configured (verificar_autenticacao), consult API quota usage (consultar_cota), get an end-to-end explanation of the Sienge purchasing process (explicar_processo_compras), and dynamically load purchase tools (carregar_compras).
With the purchases module loaded: create purchase requests, see pending purchase requests/orders, approve/reject them, and list orders pending receipt.
With the contracts module loaded (via carregar_contratos): detail supply contracts, download contract attachments, list pending contract approvals, and approve/reject contracts/addendums.
Natural-language resolution: find contracts by number, object description, or construction site; resolve internal codes/IDs server-side.
Not covered: quotation, invoice entry, contract measurement creation/approval (client exists but no tool), and some financial tools (financial is only a skeleton).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Sienge Node buscar obras ativas com 'torre' no nome"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Servidor MCP que põe o Sienge dentro do Claude — Claude Code, Claude Desktop ou qualquer cliente MCP conversando com a API do Sienge, o ERP de construção civil e incorporação da Softplan. Integração não oficial, escrita por quem usa o ERP.
Compras, contratos de suprimentos e medições viram ferramentas que o assistente chama direto: consultar um contrato com valor, prazo e saldo, baixar os anexos, ver a fila de aprovação, criar uma solicitação de compra. Tudo em português e por nome — "Residencial Aurora", "tubo de esgoto", "instalações hidrossanitárias" —, com os códigos internos resolvidos dentro do servidor.
npx -y mcp-sienge-nodeJavaScript puro (ESM), sem etapa de build e sem dependência além do SDK do MCP.
⚠️ ALFA — 0.13.1. Em reescrita. A arquitetura mudou por inteiro na série 0.7 e nomes de tool, formato de retorno e variáveis de ambiente ainda vão mudar sem aviso. Compras e contratos já gravam no ERP: use primeiro num ambiente de homologação, e leia a seção Antes de apontar para produção.
Edite o arquivo de configuração:
Sistema | Caminho |
macOS |
|
Windows |
|
{
"mcpServers": {
"sienge": {
"command": "npx",
"args": ["-y", "mcp-sienge-node"],
"env": {
"SIENGE_USERNAME": "seu-usuario",
"SIENGE_PASSWORD": "sua-senha",
"SIENGE_SUBDOMAIN": "sua-empresa",
"SIENGE_PROFILE": "compras,contratos"
}
}
}
}Reinicie o Claude Desktop depois de salvar — ele lê esse arquivo só na inicialização, e fechar a janela não encerra o processo. Use Cmd+Q (macOS) ou saia pela bandeja (Windows).
SIENGE_PROFILE pré-carrega os módulos na subida. No Claude Desktop ele não é
opcional na prática: sem ele, as ferramentas carregadas no meio da conversa
podem não aparecer — ver Se as ferramentas não aparecerem.
Deixe só os módulos que você usa; cada um custa tokens em toda mensagem.
Se preferir Bearer Token no lugar de usuário e senha, troque as duas primeiras
variáveis por "SIENGE_API_KEY": "sua-chave". SIENGE_SUBDOMAIN é sempre
necessário: ele compõe a URL de toda chamada.
Outros clientes MCP (Claude Code, Cursor, Zed) usam o mesmo formato de
command/args/env, em arquivo próprio.
Depois de reiniciar, peça ao assistente: "testa a conexão com o Sienge". Ele
deve chamar testar_conexao e responder com a latência. Se a autenticação
estiver incompleta, verificar_autenticacao diz o que falta sem gastar chamada
na API.
Related MCP server: MCP Server Node
Variável | Obrigatória | Para quê |
| ✅ | subdomínio da empresa; compõe a URL de toda chamada |
| uma das duas | Bearer Token |
| uma das duas | Basic Auth |
| — | módulos carregados já na subida. Vazio = só o núcleo |
| — | pasta onde |
| — | trocar o host da API |
A criação exige dados que não saem da credencial nem do pedido do usuário. São constantes da instalação, então ficam no ambiente e não custam nada no schema das tools:
Variável | Obrigatória | Para quê |
| ✅ | usuário do Sienge que assina a solicitação |
| — | quem registra, se for diferente de quem assina. Vazio = o solicitante |
| — | nível da EAP em que a obra apropria: |
| — | preencha se o Sienge recusar a criação citando o departamento |
| — | idem, para a categoria |
SIENGE_NIVEL_APROPRIACAO merece atenção: sem ele, um item de orçamento de
qualquer profundidade vira alvo de apropriação, e apropriar no nível errado é
erro de cadastro. Com ele, a lista de itens candidatos encolhe a ponto de o
assistente escolher sozinho e só confirmar com você.
Lista completa e comentada em .env.example.
A descrição e o schema de cada tool são reenviados ao modelo a cada mensagem. Não é uma vez na conexão: é em toda pergunta, junto com o histórico inteiro da conversa. Uma tool que ninguém vai usar naquela conversa continua sendo paga, mensagem após mensagem — e um catálogo grande também piora a escolha do modelo, que passa a decidir entre dezenas de opções parecidas.
Por isso o servidor sobe só com o núcleo e o resto entra sob demanda, agrupado por assunto:
Módulo | Carrega com | Tools | Assunto |
núcleo | (sempre carregado) | 3 | diagnóstico, credencial, conexão |
|
| 7 | solicitação, pedido, aprovação, recebimento |
|
| 4 | contrato de suprimentos, anexos e aprovação |
|
| 1 | contas a pagar e receber (esqueleto) |
Na prática: alguém pergunta "quais pedidos estão esperando aprovação?". O
assistente vê no catálogo apenas as três tools do núcleo e as ferramentas
carregar_*, cada uma com uma linha dizendo o que traz. Ele chama
carregar_compras, as sete tools de compras entram, e a conversa segue. As
tools de contratos e de financeiro nunca são carregadas — e nunca são pagas.
O que isso poupa, medido no catálogo real deste servidor:
Sessão | O que fica carregado | Custo por mensagem |
só compras | núcleo + compras | ~8,4 KB |
só contratos | núcleo + contratos | ~5,3 KB |
tudo carregado | núcleo + os três módulos | ~13,1 KB |
A diferença parece pequena em bytes e não é: ela é multiplicada pelo número de mensagens da conversa. Numa conversa de trinta trocas sobre compras, carregar contratos e financeiro junto custaria uns 141 KB de contexto que ninguém leu.
descarregar_modulos faz o caminho de volta e devolve o catálogo ao núcleo,
para quando o assunto muda no meio da conversa.
Para uma operação que sempre usa os mesmos módulos,
SIENGE_PROFILE=compras,contratos deixa o recorte pronto na subida, sem
depender do carregamento dinâmico. É a escolha certa quando você sabe o que
vai usar; o carregamento sob demanda existe para quando não se sabe.
carregar_*Quando o catálogo muda, o servidor avisa o cliente (tools/list_changed) para
ele buscar a lista de novo. Alguns clientes, entre eles o Claude Desktop, não
reagem no meio da conversa: a lista que o assistente enxerga foi congelada
quando a sessão começou. As tools ficam registradas no servidor e invisíveis do
outro lado.
O sintoma engana. O assistente não recebe "ainda não indexei"; ele recebe uma recusa e conclui que as ferramentas não existem — foi assim que uma sessão chegou a afirmar que o módulo de contratos não estava disponível, com o módulo carregado e funcionando.
Dois caminhos:
Na hora: a resposta do carregar_* traz os nomes exatos das ferramentas.
Chamar pelo nome costuma funcionar mesmo com a lista desatualizada.
De vez: pré-carregue com SIENGE_PROFILE=compras,contratos. Os módulos
sobem antes do primeiro tools/list, então não há mudança de catálogo para o
cliente ignorar. O preço é pagar esses módulos em toda mensagem, inclusive
nas conversas que não usam nenhum deles.
Reescrita em andamento. A 0.7.0 trocou a arquitetura inteira e recomeçou o catálogo de tools pelo ciclo de compras; a 0.10.0 abriu o de contratos de suprimentos, que é onde a obra contrata serviço e paga por medição.
Módulo | Tools | Estado |
| 3 | ✅ diagnóstico e autenticação |
| 7 | 🔨 solicitação e pedido; falta cotação e nota fiscal |
| 4 | 🔨 consulta, anexos e aprovação; medição pronta em |
| 1 | ⚠️ apenas um esqueleto de teste, não lê nada do ERP |
Tool | O que faz |
| confirma que o servidor está no ar e há quanto tempo |
| testa a credencial contra a API, com uma chamada barata |
| qual mecanismo está configurado, sem chamar a API |
| o processo de compras de ponta a ponta, e o que este servidor não cobre |
| cria uma solicitação, com vários itens, a partir de nomes e com prévia antes de gravar |
| a fila de solicitações pendentes, agrupada por solicitação |
| aprova ou reprova itens e solicitações, conferindo antes contra a fila real |
| a fila de pedidos pendentes, com itens e fornecedor resolvidos |
| aprova ou reprova pedidos de compra, com o valor na prévia — não envia e-mail, ver abaixo |
| o que foi aprovado e ainda não chegou |
| tudo de um contrato numa chamada: fornecedor, valor, prazo, saldo e os itens com preço unitário |
| salva os anexos do contrato numa pasta local e devolve o caminho |
| contratos e aditivos pendentes, com fornecedor, valor, prazo, motivo e itens |
| aprova ou reprova os contratos escolhidos, conferindo contra a fila real e com prévia |
| trazem as tools do módulo |
| libera o contexto dos módulos carregados |
O Sienge percorre até seis etapas. compras_processo descreve todas ao
assistente — inclusive as que este servidor não cobre, para que ele não
prometa o que não faz.
Etapa | Cobertura |
1 · Solicitação | criar ✅ · consultar ❌ |
2 · Aprovação da solicitação | fila ✅ · aprovar ✅ · reprovar ✅ |
3 · Cotação | ❌ |
4 · Pedido de compra | fila ✅ |
5 · Aprovação do pedido | fila ✅ · aprovar ✅ · reprovar ✅ |
6 · Nota fiscal | pendências ✅ · lançar ❌ |
As escritas desta etapa são três: criar solicitação, decidir solicitação e decidir pedido de compra.
Outro módulo, outro ciclo — contratos_*, carregado à parte por
carregar_contratos, sem nenhuma dependência de compras. Não é a continuação
do processo de compra: é o caminho alternativo. A compra termina numa
entrega; o contrato, numa medição — alguém confere quanto do serviço
foi executado, e é isso que vira conta a pagar.
O módulo expõe quatro tools: contratos_detalhar,
contratos_baixar_anexos, contratos_pendentes_aprovacao e
contratos_decidir. O resto do ciclo já está implementado e testado em
client/supplyContractClient.js, sem tool declarada — porque tool parada custa
tokens em toda mensagem, e porque as escritas de medição gravam no ERP.
Etapa | Client | Tool |
Contrato — consultar | ✅ | ✅ |
Contrato — listar por obra e período | ✅ | — |
Anexos — baixar | ✅ | ✅ |
Anexos — anexar | ❌ | — |
Contrato e aditivo — listar pendentes | ✅ | ✅ |
Contrato e aditivo — aprovar e reprovar | ✅ | ✅ |
Medição — consultar | ✅ | — |
Medição — criar | ✅ | — ✏️ grava |
Medição — autorizar e reprovar | ✅ | — ✏️ grava |
Liberação (o título a pagar) | ✅ consultar · ❌ liberar — a API não expõe | — |
Aditivos — consultar | ✅ | — |
Três coisas deste recurso não se adivinham, e as tools já as tratam por dentro:
O contrato não tem id. A identidade é o par documento + número (CTS,
325), e ninguém sabe de cabeça que o documento é CTS. As tools aceitam o
número solto, parte do objeto ou só a obra.
Não existe listagem sem período. Toda busca varre uma janela de 4 anos e diz na resposta qual janela varreu — ausente na janela não é inexistente.
Não existe saldo de item de contrato. O saldo que a prévia de medição mostra é derivado da última medição e vai rotulado como tal; ele ignora aditivo posterior, então estourá-lo é aviso, nunca bloqueio.
Uma escrita de contrato está exposta: decidir (aprovar ou reprovar). Criar medição e decidir medição existem no client e esperam ser pedidas.
contratos_detalhar resolve um contratoVale abrir esta, porque quase tudo que ela faz existe para contornar um jeito de a resposta sair errada sem erro nenhum.
A informação está espalhada por cinco endpoints: o cabeçalho num, o saldo noutro, o fornecedor no cadastro de credores, as obras num terceiro, os itens num quarto — e os itens ainda vivem por planilha. Encadear isso como tools faria cada passo reenviar a conversa inteira ao modelo. Por isso é uma chamada só, e a tradução acontece no servidor, onde é de graça.
1 · De quem estamos falando. O contrato não tem id: a identidade é o par
documento + número (CTS, 325), e ninguém sabe de cabeça que o documento é
CTS. Quatro caminhos, do mais barato ao mais caro:
Você informa | O que acontece |
documento e número | um GET direto, confirma que existe |
só o número | varre a janela e casa pelo número |
um texto ( | varre a janela e casa pelo objeto |
só a obra | varre a janela dela; havendo um contrato só, resolve |
A obra vem antes, por nome, descartando os cadastros marcados "NÃO USAR" — obra desativada que a conta mantém por histórico.
2 · A janela. A API não lista contrato sem período; não existe "todos". A
varredura usa 4 anos até hoje e devolve, na resposta, qual janela varreu.
Sem isso, "não achei" vira "não existe", que é outra coisa — a mensagem diz
onde olhou e que desde amplia.
3 · Quando o nome não casa, a tool não adivinha. O nome do cadastro raramente é o nome que a pessoa usa: em produção, "instalações hidrossanitárias" está gravado como "SERVIÇO DE INSTALAÇÃO HIDRAULICA, ESGOTO, GÁS E INCÊNDIO". Isso é sinonímia de obra, não de grafia, e nenhuma regra de texto liga os dois sem chutar. Então a resposta traz os contratos da janela ordenados por relevância, cada um com o seu par — a obra em que isso aconteceu tem 75 contratos em quatro anos, e ordenar por data escondia justamente o certo.
4 · O cabeçalho é buscado de novo, mesmo quando o passo 1 já achou o
contrato na listagem: só o GET de um contrato devolve materialBalance e
laborBalance. A listagem não traz saldo.
5 · A obra tem dois ids, e o óbvio é o errado.
/supply-contracts/buildings devolve buildingID (interno) e
buildingIdView (código no Sienge). Só o View é aceito nos demais endpoints:
/supply-contracts/items?buildingId=21 → 404 "Obra 21 não encontrada"
/supply-contracts/all?buildingId=21 → 200 com 85 contratos de OUTRA obra
/supply-contracts/all?buildingId=20 → 200 com os 75 contratos certosO 404 aparece; os 85 contratos errados, não. Conferido contra produção — é a única falha aqui capaz de produzir uma resposta confiante e completamente errada.
6 · Os itens saem por planilha (obra × unidade construtiva); não existe
"todos os itens do contrato". incluir_itens: false corta essas N chamadas
quando a pergunta não envolve item.
O ERP guarda material e mão de obra sempre separados — eles medem e pagam separado. Ninguém pergunta assim.
Campo | De onde sai |
| material + mão de obra |
| saldo de material + saldo de mão de obra |
| início, fim e |
| preço de material + de mão de obra, por item |
| quantidade × preço unitário |
| derivado: item sem |
Uma regra atravessa todas: ausência não vira zero. saldo_total some da
resposta quando a API não mandou o campo, em vez de virar 0 — saldo zero é
"acabou", saldo ausente é "não sei", e a listagem nunca traz saldo.
Duas perguntas, duas tools:
"Quais contratos estão pendentes de aprovação no Sienge?" →
contratos_pendentes_aprovacao"Aprova o CTS/524 e o CTS/596", "aprova todos" ou "reprova o CTS/596" →
contratos_decidir
A lista vem completa numa chamada. Para cada pendente: fornecedor, obra, valor, prazo, o motivo de estar pendente — o Sienge informa, por exemplo, "valor total do contrato excede o limite permitido para o usuário" — e os itens com preço unitário. Nada disso exige o assistente chamar outra tool.
Aditivo aparece como aditivo. O Sienge não tem aprovação separada de
aditivo: quando um aditivo é registrado, o contrato inteiro volta a aguardar
autorização, na alçada ADDENDUM, e é aprovado pelo mesmo caminho. A lista traz
o que o aditivo mais recente mudou — mas a API não diz qual aditivo está
pendente, então isso vai rotulado como "o mais recente", não como certeza.
"Aprova todos" não é um atalho. Não existe "aprovar tudo que estiver
pendente". O assistente passa a lista que acabou de mostrar — e é isso que
impede aprovar um contrato que entrou na fila depois da listagem, sem
ninguém ter olhado para ele. O que ficou de fora volta em continuam_pendentes.
Antes de gravar, a fila é relida. Se outra pessoa aprovou um dos contratos nesse meio-tempo, ele não está mais lá e não é gravado. E se uma referência da lista estiver errada, nenhuma é aprovada — um número trocado no meio não deixa metade aprovada.
Aprovar e reprovar ficam na mesma tool, escolhidos em decisao, e passam
pela mesma conferência — nenhuma das duas tem volta. Sem decisao, a tool
aprova; reprovar nunca é o padrão. Ao reprovar, o motivo vai em observacao e
fica gravado no contrato.
Só aparece o que ainda está para decidir. A fila "aguardando autorização" do Sienge traz mais do que o nome promete, e três grupos ficam de fora — da lista e da decisão:
Fica de fora | Por quê |
Cadastro em inclusão | alguém ainda está cadastrando: valor zerado, sem obra |
Reprovados | reprovar não tira o contrato da fila de "aguardando" |
Concluídos e revogados | o contrato já terminou ou foi desfeito; não há o que autorizar |
O segundo é o que mais engana. Em produção, dois contratos reprovados apareciam ao mesmo tempo no filtro de "aguardando autorização" e no de "reprovados". Confiando no nome do filtro, a tool ofereceria para aprovar o que alguém já reprovou. Dos 9 contratos que o Sienge chamava de pendentes, 3 eram de fato para decidir.
Uma recusa do Sienge num contrato não desfaz os outros.
Comece em homologação. Uma solicitação criada por engano não pode ser
apagada pela API: o Sienge não expõe DELETE de solicitação.
A criação não é atômica. A API grava cabeçalho e itens em dois POST.
Se o segundo falhar, fica uma solicitação sem itens; o retorno diz o id para
você resolver pela tela.
Decidir não tem volta. A API não expõe endpoint que desfaça uma
autorização nem uma reprovação. A tool confere contra a fila real e exige
confirmar: true, mas depois de gravado só o ERP resolve. Deixar um item
sem decisão é legítimo: liste só o que foi decidido.
A prévia é o portão. Sem confirmar: true, compras_criar_solicitacao
resolve tudo e devolve o que seria gravado, sem gravar. Confira a unidade de
medida e o item de orçamento ali — é o último ponto antes do ERP.
Aprovar pedido pela API não envia e-mail — bug do Sienge. Na tela, aprovar um pedido dispara os envios parametrizados: a via ao fornecedor, o aviso ao usuário do Sienge e o relatório à obra. Pelo endpoint, nenhum deles sai, mesmo com o envio automático ligado no ERP. Não é configuração faltando nem limitação deste servidor: é o endpoint que não executa o gatilho que a tela executa. O pedido fica aprovado e ninguém é avisado — combine o envio por fora. A tool repete esse aviso em toda resposta de aprovação.
Aprovar ou reprovar contrato não tem volta. A API não expõe endpoint que
desfaça nenhuma das duas. A tool relê a fila e exige confirmar: true, mas depois de
gravado só o ERP resolve. O aviso ao responsável só sai se o ERP estiver
parametrizado para sempre enviar.
Baixar anexo escreve no seu disco, não no ERP. Os arquivos vão para
SIENGE_PASTA_ANEXOS, numa subpasta por contrato. A tool grava os bytes como
vieram e não lê o conteúdo — não espere dela um resumo do PDF.
Não há trilha de auditoria. A versão anterior gravava um log de escrita; essa parte ainda não foi reescrita.
git clone https://github.com/frlorenzon/MCP-Sienge-Node.git
cd MCP-Sienge-Node
npm install
cp .env.example .env # preencha as credenciais
npm startnpm test137 testes com o runner nativo do Node, sem dependência nenhuma. Nenhum toca
a API do Sienge — sobem um servidor HTTP local que responde nos schemas de
spec/openapi.yaml, então rodam offline e não consomem cota.
Testar contra HTTP de verdade, em vez de dublar makeRequest, é o que faz a
suíte cobrir o que mais quebrou neste projeto: o corpo exato enviado ao ERP, o
formato de erro do Sienge e a paginação. Cada caso corresponde a um defeito que
já aconteceu contra o Sienge real.
src/
├── index.js bootstrap stdio
├── config.js credenciais e resolução de auth
├── toolsGroupRouter.js tools/list, tools/call e carregamento sob demanda
├── api/ um arquivo por recurso REST do Sienge
│ ├── purchase-requests-v1.js
│ ├── purchase-orders-v1.js
│ ├── supply-contracts-v1.js
│ ├── supply-contracts-measurements-v1.js
│ ├── building-cost-estimations-v1.js
│ ├── creditor-v1.js
│ └── cost-center-v1.js
├── client/
│ ├── siengeClient.js o único ponto que fala HTTP com o Sienge —
│ │ makeRequest para JSON, baixarArquivo para bytes
│ ├── purchaseClient.js compõe as funções de api/ no que uma pergunta de
│ │ negócio precisa: resolve nomes, agrupa, projeta
│ └── supplyContractClient.js idem, para contratos e medições
├── modules/ o que vira tool: core, purchase, supplyContract,
│ financial
└── knowledge/ o processo de compras (conhecimento, não API)
spec/openapi.yaml a especificação publicada do Sienge
test/ Sienge falso + os casosTrês camadas, e a divisão importa por causa do custo: modules/ é a
superfície MCP e custa tokens em toda requisição; api/ e client/ não custam
nada. Toda lógica que puder descer, desce — é por isso que
compras_criar_solicitacao aceita "tubo de esgoto" e "instalações
hidráulicas" em vez de ids: resolver nomes dentro do servidor é de graça,
enquanto fazer o modelo encadear quatro tools para descobrir os mesmos ids
reenvia a conversa inteira a cada passo.
spec/openapi.yamlCópia local da especificação do Sienge, com a procedência em
spec/README.md. Sem ela, nome de campo vira palpite — e
palpite falha em silêncio: um filtro inexistente é ignorado pelo servidor, um
campo com nome errado volta undefined, e o resultado sai vazio sem erro
nenhum. Confira ali antes de escrever qualquer coisa em src/api/.
PolyForm Noncommercial 1.0.0 — uso livre para fins não comerciais. Para uso comercial, contate o autor.
Carrega as ferramentas de compras: fila de pedidos pendentes de aprovação, já com itens, insumos, fornecedores e obras resolvidos. Chame quando a conversa for sobre pedidos de compra, aprovação ou fornecedores.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It explains that the tool loads purchase tools with resolved data, which provides context, but it does not explicitly state whether this is a read-only operation or if there are side effects. Since 'carregar' implies loading, it's likely harmless, but this is not made explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action and content, followed by usage guidance. Every sentence earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description is fairly complete: it states what the tool does and when to call it. It lacks details about return values or prerequisites like authentication, but given the simplicity and the existence of sibling tools like verificar_autenticacao, it is sufficiently contextual.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100%. According to the baseline rule, 0 parameters merit a baseline of 4. The description adds no parameter details because none exist, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Carrega' (loads) and the resource 'ferramentas de compras' (purchase tools), and specifies the content loaded (queue of pending approvals with resolved items, inputs, suppliers, and works). It distinguishes itself from siblings by focusing on loading the purchasing context rather than testing connections or explaining processes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Chame quando a conversa for sobre pedidos de compra, aprovação ou fornecedores' (call when the conversation is about purchase orders, approval, or suppliers), providing clear when-to-use guidance. However, it does not mention alternatives or when-not-to-use, so it misses the full 5-level specificity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mostra o consumo e o saldo das cotas diárias da API do Sienge, que são duas e independentes: REST, larga, e BULK, estreita. Contas a pagar, contas a receber e itens de nota em volume consomem BULK, e é ela que esgota primeiro. Consulte antes de uma sequência dessas consultas. O saldo só é calculado com SIENGE_MCP_API_PACKAGE configurada.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that there are two independent quotas (REST and BULK), that BULK is consumed by specific operations and exhausts first, and that balance calculation requires the SIENGE_MCP_API_PACKAGE environment variable. This exceeds baseline expectations for a simple status tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the main purpose appears in the first sentence, followed by essential operational details (quota types, consumption patterns, configuration requirement). Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description is remarkably complete. It explains what the tool shows, when to use it, the behavior of the two quotas, and a critical prerequisite. An agent has all necessary information to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is complete by definition. The description appropriately focuses on what the tool reports rather than parameter details, matching the baseline for 0-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to show consumption and balance of the Sienge API's daily quotas. It uses a specific verb ('Mostra'), identifies the resource (daily quotas), and naturally distinguishes itself from sibling tools like connection tests and purchase loaders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to 'Consulte antes de uma sequência dessas consultas' (consult before a sequence of these queries), giving a concrete use case. It does not mention exclusions or alternatives, but given the sibling tools are unrelated, the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explica o processo de compras do Sienge de ponta a ponta: as 5 etapas, quais são opcionais, os caminhos válidos e os limites da API.
Consulte ANTES de responder qualquer pergunta sobre solicitações, cotações, pedidos de compra ou aprovações. Evita os erros mais comuns — procurar preço numa solicitação de compra, que não tem preço, ou supor que todo pedido nasceu de uma solicitação.
A resposta diz, por etapa, quais tools este servidor tem de fato: nem toda etapa do processo é coberta.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It is transparent about what the tool returns: a staged explanation of the purchase process, including optional steps, valid paths, API limits, and which stages are actually covered by server tools ('nem toda etapa do processo é coberta'). This sets accurate expectations about the tool's advisory role.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured, and front-loaded with the primary purpose. Each sentence earns its place: the first defines scope, the second gives usage guidance and error prevention, and the third sets expectations about tool coverage. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description is remarkably complete. It explains what the tool does, when to use it, what content it will provide, and its limitations. The sibling tool names further clarify the context, making this description fully sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline for this dimension is 4. The description appropriately does not waste space on parameter details; it focuses on the tool's purpose and output, which is all that is needed for a no-input advisory tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool's specific purpose with a clear verb ('Explica') and resource ('processo de compras do Sienge'), and goes further to specify the content (5 etapas, opcionais, caminhos válidos, limites da API). It clearly distinguishes itself from sibling tools, which perform data retrieval or connection tests, by positioning itself as a process guide.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage direction: 'Consulte ANTES de responder qualquer pergunta sobre solicitações, cotações, pedidos de compra ou aprovações.' It also mentions common pitfalls to avoid, which helps the agent decide when to use this tool before attempting data queries, and notes that the tool identifies which stages have actual tool coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Testa se as credenciais autenticam de fato contra a API do Sienge, com uma chamada real de baixo custo. Use para diagnosticar falha de conexão ou credencial; para apenas ver qual mecanismo está configurado, sem chamar a API, use verificar_autenticacao.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden. It discloses key behavioral traits: the tool performs a real API call ('chamada real') and is low-cost ('baixo custo'). However, it does not explicitly state whether the call has side effects or how results are returned, though the nature of an authentication test implies a read-only check. This is useful but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and then provides usage guidance with an alternative. Every sentence earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no output schema), the description is nearly complete: it tells what it does, when to use it, and how it differs from the sibling. The only gap is the lack of explicit return-value or success/failure behavior, which the agent might need to know since there is no output schema to clarify it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema already covers everything (100% coverage vacuously). The description adds no parameter details, but none are needed. Baseline for 0 parameters is 4, and the description does not detract from that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to test whether credentials actually authenticate against the Sienge API via a real, low-cost call. It uses a specific verb ('Testa') and resource ('credenciais contra a API do Sienge'), and distinguishes itself from the sibling tool 'verificar_autenticacao' by noting that this one makes a real API call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides use cases: 'Use para diagnosticar falha de conexão ou credencial' (use to diagnose connection or credential failure). It also gives a clear alternative: 'para apenas ver qual mecanismo está configurado, sem chamar a API, use verificar_autenticacao'. This meets the highest standard of when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mostra qual mecanismo de autenticação está configurado (Bearer Token ou Basic Auth) e se as credenciais estão completas. Não chama a API — para verificar se elas de fato funcionam, use testar_conexao.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that the tool does not call the API, which is a key behavioral trait (non-side-effect). It also describes what it shows (mechanism and credential completeness). It could add more detail about return format or edge cases, but for a simple inspection tool, this is sufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the main purpose, then adds the critical exclusion and alternative tool reference. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description is complete: it explains what the tool displays, what it does not do (call the API), and directs to the sibling tool for functional verification. No further context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and schema coverage is trivially 100%. The baseline for 0 parameters is 4, and the description does not need to explain parameters since there are none. It adds no parameter-related info, which is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: showing which authentication mechanism is configured (Bearer Token or Basic Auth) and whether credentials are complete. It uses a specific verb ('Mostra') and resource ('autenticação configurada'), and explicitly distinguishes itself from the sibling tool 'testar_conexao' by noting it does not call the API.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: it tells the agent when to use this tool (to inspect configuration) and when not to (to verify actual functionality), directing to the alternative 'testar_conexao' for actually testing credentials. This meets the 'when/when-not/alternatives' criterion perfectly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.6.0carregar_comprasconsultar_cotaexplicar_processo_comprastestar_conexaoverificar_autenticacaoScored across 5 tools
The two authentication tools (testar_conexao and verificar_autenticacao) are similar but explicitly cross-referenced to clarify their distinct purposes: one tests real API access, the other inspects configuration. The remaining three tools each target a clearly unique aspect (quotas, process explanation, and loading purchasing tools), so overall ambiguity is low.
All tool names follow a consistent verb_noun pattern in snake_case: testar_conexao, verificar_autenticacao, consultar_cota, explicar_processo_compras, carregar_compras. This uniform structure makes the set predictable and easy to navigate.
With 5 tools, the server is well within the ideal 3-15 range. Each tool serves a distinct purpose—auth testing, auth config, quota checking, process explanation, and loading purchase tools—so the count is appropriate for a focused Sienge integration server.
The tool set lacks direct CRUD or query operations for core Sienge resources like purchase orders, suppliers, or invoices, which are essential for a purchasing-focused server. The description of explicar_processo_compras explicitly states that not every stage of the procurement process is covered, and carregar_compras hints at additional tools that are not actually exposed, leaving significant functional gaps.
MCP server for Brazilian Federal Senate open data (legislative, administrative, e-Cidadania).
MCP server for Codat — companies, connections, invoices, bills and financial statements.
MCP server for Hostinger API
Brazilian fiscal MCP server - issue NF-e, NFC-e, NFS-e, CT-e, MDF-e and DC-e via SEFAZ.
