@expertcustom/nfsnacional-mcp

Servidor MCP do NFS-e Nacional (LiNFe). Dá a uma IA acesso às consultas fiscais e ao preparo de NFS-e do sistema.

Uso interno. Não emite documento fiscal — o que a IA prepara vira rascunho, e a emissão continua sendo uma ação do usuário no sistema.

Configuração

Por variável de ambiente:

| Variável | Obrigatória | Padrão | |---|---|---| | NFSNACIONAL_API_KEY | sim | — | | NFSNACIONAL_API_URL | não | http://localhost:8080/api/v1 | | NFSNACIONAL_TIMEOUT_MS | não | 30000 |

A chave é emitida pelo próprio sistema, em Configurações → API, e define a qual escritório o servidor tem acesso. Ela vem com escopos: peça os de consulta e de preparo conforme o que a IA vai fazer.

Um servidor por escritório

A chave é a fronteira do escritório: a API resolve o tenant a partir dela, e nenhum cabeçalho muda isso. Uma chave só atendendo vários escritórios não os separa — todos leriam os dados do tenant dono da chave. Registre um MCP server (com sua chave) por escritório.

Quem está conversando

A chave diz o escritório e para aí; todas as conversas dele chegam com a mesma credencial de máquina. Quem diz a pessoa é o cabeçalho X-Aurora-User, que este servidor monta a partir do userId que a plataforma injeta em cada tool call — e é ele que faz a API filtrar as empresas por vínculo, como a tela faz.

Nada a configurar: as tools declaram o campo userId e a Aurora o preenche. Mas a partir da 0.3.0 a API pode exigir essa identidade (ACESSO_MCP_EXIGIR_IDENTIDADE=true, o padrão) — um cliente MCP mais antigo, ou outro que não injete o campo, recebe 403 nas rotas com empresa.

Uso

command: npx
args:    ["-y", "@expertcustom/[email protected]"]
env:     { NFSNACIONAL_API_URL: "...", NFSNACIONAL_API_KEY: "..." }
timeout: 60000

Fixe a versão — sem ela, uma publicação nova alcança todas as IAs ligadas de uma vez. O timeout acima do padrão dá margem às consultas mais pesadas.

Build

npm install
npm run build

Suporte

Documentação interna e detalhes de integração: repositório do NFS-e Nacional.