Inteligência Artificial
MCP read-only: tools de estoque, resumo, NFe, financeiro e status SEFAZ.
Neste capítulo (7 seções)
O Nexus expõe um servidor MCP (Model Context Protocol) com ferramentas de somente leitura para assistentes de IA: estoque, vendas, financeiro, NFe e status SEFAZ no contexto da empresa autenticada.
O que o MCP faz e o que não faz#
| Faz | Não faz |
|---|---|
| Consultar estoque, resumos e títulos a vencer | Criar venda, emitir NFe ou alterar cadastro — isso se faz nas telas do ERP |
| Listar NFe e status SEFAZ | Transmitir ou cancelar documentos |
| Responder no escopo do business_id da sessão/token | Acessar outras empresas sem autenticação |
Ferramentas disponíveis#
Dez ferramentas de leitura, todas restritas à empresa do token. Datas usam o formato
AAAA-MM-DD.
| Tool | Para que serve | Parâmetros |
|---|---|---|
| contexto_nexus escopo: contexto |
Situa o assistente: empresa, ambiente fiscal e o que ele pode consultar. É por onde o agente deve começar. | Nenhum. |
| estoque_produto escopo: estoque |
Busca produtos e devolve a quantidade em estoque (somando variações e locais). | busca — nome, SKU ou código (obrigatório)limite — 1 a 50, padrão 10 |
| resumo_do_dia escopo: vendas |
Resumo de vendas de um dia, com ranking de produtos. | data — padrão hojetop_produtos — 1 a 20, padrão 5 |
| resumo_do_periodo escopo: vendas |
Mesmo resumo, entre duas datas. | data_inicio — padrão dia 1 do mêsdata_fim — padrão hojetop_produtos — 1 a 20, padrão 5 |
| consultar_venda escopo: vendas |
Detalhes de uma venda específica. | identificador — nº da fatura, referência, id interno, nº da NFe ou chave de acesso |
| consultar_contato escopo: financeiro |
Dados e saldo de cliente ou fornecedor. | busca — nome, razão social, CNPJ/CPF ou telefonelimite — 1 a 50, padrão 10 |
| contas_a_vencer escopo: financeiro |
Títulos a receber ou a pagar em uma janela de vencimento. | direcao — receber (padrão) ou pagarvencimento_de / vencimento_ateapenas_vencidas — só os já vencidoslimite — 1 a 200, padrão 50 |
| saldo_financeiro escopo: financeiro |
Saldo das contas financeiras da empresa. | Nenhum. |
| listar_nfe escopo: fiscal |
Lista NFe do período, com paginação. | data_inicio / data_fimsituacao — APROVADO, CANCELADO, REJEITADO ou NOVO (AUTORIZADO vale como sinônimo de aprovado)limite — 1 a 200, padrão 20pagina — padrão 1 |
| status_sefaz escopo: fiscal |
Situação do serviço da SEFAZ. | uf — sigla de 2 letras; sem ela, usa a UF da empresa |
Recursos (resources)#
Além das ferramentas, o servidor publica um recurso de contexto estático:
| Recurso | URI | Para que serve |
|---|---|---|
| Glossário fiscal do Nexus | nexus://glossario/fiscal |
Vocabulário fiscal (CFOP, CST/CSOSN, chave de acesso, estados do documento) para o assistente interpretar os resultados sem inventar significado. |
Tokens de acesso e escopos#
Todo acesso ao MCP passa por um token pessoal. Ele é emitido em
Superadmin → Integrações MCP (/integracoes/mcp-tokens) — tela de quem
administra a plataforma, não do cliente final. O token herda a empresa do usuário
a quem pertence: um token nunca enxerga dados de outro tenant.
| Campo | O que é / para que serve | Como preencher |
|---|---|---|
| Usuário | Dono do token; define a empresa e o alcance dos dados. | Obrigatório. Usuário sem empresa vinculada é recusado — o token não teria o que consultar. |
| Nome do token | Identificação de quem/o que usa o token. | Obrigatório, até 60 caracteres. Diga a automação: “painel do gerente”, “bot WhatsApp”. |
| Escopos | Domínios de leitura liberados. | Obrigatório, ao menos um. Marque só o necessário. |
| Validade em dias | Prazo até a expiração automática. | Opcional; em branco usa o padrão da instalação (365 dias). 0 = sem expiração — evite. |
Escopos disponíveis#
| Escopo | Libera |
|---|---|
nexus:read | Tudo em leitura — abre todos os domínios abaixo. |
nexus:contexto:read | Contexto da empresa e do ambiente fiscal. |
nexus:vendas:read | Consulta de vendas e resumos de faturamento. |
nexus:fiscal:read | NFe emitidas e status da SEFAZ. |
nexus:financeiro:read | Saldos, contas a vencer e saldo de contatos. |
nexus:estoque:read | Produtos e quantidade disponível. |
O domínio contexto é liberado para qualquer token do namespace nexus::
o servidor orienta o assistente a se situar antes de consultar, e negar isso o deixaria cego.
A ability coringa * do Sanctum não vale para o MCP — ela abriria a API
inteira da aplicação, não apenas as leituras do servidor.
Fluxo de uso com assistente#
- Configure o cliente MCP (Cursor, Claude Desktop, etc.) apontando para o endpoint do servidor (
/mcp/v1/nexusno domínio da sua instalação) e informe o token emitido como credencial. - Faça perguntas no escopo das tools (“qual o estoque do SKU X?”, “resumo de vendas de hoje”).
- Valide números críticos na tela do ERP antes de decidir compra/preço.
- Para ações de escrita (emitir, pagar, ajustar), use o sistema — não o MCP.
Checklist e problemas#
| Conferência | OK? |
|---|---|
| MCP habilitado e autenticado na instância | ☐ |
| Token com escopo mínimo necessário | ☐ |
| Equipe sabe que é somente leitura | ☐ |
| Respostas sensíveis não vão para canais públicos | ☐ |
| Sintoma | Causa | Ação |
|---|---|---|
| Tool não encontrada | Cliente desatualizado / server não carregou tools | Reiniciar servidor MCP; conferir app/Mcp |
| Dados de outra empresa | Token/sessão errada | Reautenticar no business correto |
| Estoque “diferente da tela” | Filtro de local; cache do assistente | Repetir pergunta com SKU; conferir stock report |
| Erro de validação | Parâmetro obrigatório ausente | Informar busca/período conforme schema |