# MCP do NotaGuard > Documentação canônica: https://notaguard.com.br/desenvolvedores/mcp O NotaGuard publica um servidor MCP: um endereço que assistentes de IA conectam à conta de uma empresa para ler, analisar e organizar as notas fiscais dela em linguagem natural. MCP é um protocolo aberto, então serve o assistente que você já usa. Conectado, o assistente responde perguntas como "quanto gastei com esse fornecedor no trimestre", acha a nota pelo nome do produto dentro do XML, aponta o que ainda falta manifestar na SEFAZ e, se você autorizar, prepara e emite NFS-e. ## O que dá para pedir Perguntas que o servidor responde hoje, com os dados extraídos do XML das notas da empresa. ### Contexto - Quais empresas eu tenho no NotaGuard? - Está tudo certo com a minha empresa? O certificado vence quando? ### Notas - Quanto entrou de nota em julho? - Acha a nota em que aparece "cabo de rede" na descrição do item. - Me manda o XML da nota 12345. ### Etiquetas - Cria a etiqueta "obra São Paulo" e aplica nas notas desse fornecedor no mês. ### Análise - Quais foram meus dez maiores fornecedores no semestre? - Quanto paguei de ICMS por CFOP no ano? - O que vence essa semana nas contas a pagar? ### Compliance - Tem nota esperando manifestação? Quanto tempo falta em cada uma? ### Manifestação - Dá ciência nas notas pendentes desse fornecedor. - Desconhece essa nota, não foi a gente que comprou. ### Emissão de NFS-e - Prepara uma nota de consultoria de R$ 2.000 para esse cliente. - Quais modelos de nota eu já tenho salvos? - Emite os rascunhos que eu revisei, em produção restrita primeiro. ### NFS-e - Sorocaba já emite NFS-e pelo Emissor Nacional? ## De onde vêm as notas O NotaGuard consulta a SEFAZ com o certificado digital da empresa e recebe as NF-e, as NFS-e e os CT-e emitidos contra o CNPJ ou o CPF dela. Guarda o XML de cada uma, extrai itens, tributos, eventos e duplicatas, e emite NFS-e. O servidor MCP é uma porta para esse acervo. Ele não consulta uma base pública de notas: consulta a base da sua empresa, e por isso depende de uma conta com notas dentro. O teste grátis de 7 dias já vem com o MCP liberado: https://notaguard.com.br/teste-gratis ## Já usa o NotaGuard? Conecte agora Este é o endereço do servidor. Não há pacote para instalar nem chave para cadastrar. ``` https://mcp.notaguard.com.br ``` - **Endereço:** https://mcp.notaguard.com.br - **Transporte:** Streamable HTTP - **Autenticação:** OAuth 2.1, com registro dinâmico de cliente - **Ferramentas:** 27 tools e 2 prompts - **Clientes:** ChatGPT, Claude, Claude Code, Codex, Cursor e VS Code têm o passo a passo aqui; qualquer outro que fale o protocolo também conecta - **Instalação:** Nenhuma. Servidor remoto, sem pacote para baixar ### O que você precisa antes de conectar 1. **Conta no NotaGuard.** O servidor abre a sua conta, não uma base pública. O teste grátis de 7 dias serve para conectar e experimentar. 2. **Uma empresa cadastrada.** As tools trabalham sobre uma empresa (CNPJ ou CPF). Sem empresa cadastrada, a primeira tool devolve lista vazia e o assistente não tem por onde começar. A empresa se cria no painel. 3. **Plano com acesso ao MCP.** Incluso no Professional e no Enterprise. No Basic e no Standard, entra pelo adicional MCP + API de R$ 19,90 por mês, contratado na assinatura. Durante o teste grátis o acesso está liberado. 4. **Certificado digital A1, para o que toca a SEFAZ.** Monitorar, manifestar e emitir dependem do certificado da empresa. Consultar e analisar o que já está no acervo, não. A senha do certificado nunca é pedida no chat: o upload é no painel. 5. **Um cliente com suporte a MCP remoto.** O cliente precisa falar Streamable HTTP e fazer o login por OAuth. Claude, Claude Code, Cursor e VS Code fazem. A lista abaixo tem o passo de cada um. ### Instalação, por cliente #### Claude (claude.ai, aplicativo e celular) 1. Abra Configurações e vá em Conectores. 2. Clique em Adicionar conector personalizado. 3. Cole https://mcp.notaguard.com.br no campo de endereço e confirme. 4. O Claude abre o login do NotaGuard. Entre e marque as permissões que quer conceder. Em conta Team ou Enterprise o caminho é Configurações da organização e depois Conectores, e quem adiciona é o proprietário da organização. #### Claude Code 1. Rode o comando abaixo no terminal. 2. Dentro do Claude Code, rode /mcp e siga o login no navegador. ```bash claude mcp add --transport http notaguard https://mcp.notaguard.com.br ``` #### Cursor 1. Crie ou edite ~/.cursor/mcp.json, para valer em todos os projetos, ou .cursor/mcp.json na raiz de um projeto. 2. Reabra o Cursor e autorize o NotaGuard quando ele pedir o login. Arquivo: `~/.cursor/mcp.json` ```json { "mcpServers": { "notaguard": { "type": "streamable-http", "url": "https://mcp.notaguard.com.br" } } } ``` #### VS Code (GitHub Copilot, modo agente) 1. Rode MCP: Add Server na paleta de comandos, ou escreva o arquivo abaixo à mão. 2. Abra o modo agente do Copilot e autorize o NotaGuard no login que aparece. Arquivo: `.vscode/mcp.json` ```json { "servers": { "notaguard": { "type": "http", "url": "https://mcp.notaguard.com.br" } } } ``` #### ChatGPT 1. Em Configurações, abra Apps e entre em Configurações avançadas. 2. Ligue o Modo desenvolvedor. 3. Crie um conector personalizado, também chamado de app, e cole https://mcp.notaguard.com.br no endereço. 4. Entre no login do NotaGuard que abrir e marque as permissões que quer conceder. É no ChatGPT web, em conta Plus, Pro, Business, Enterprise ou Edu; o plano gratuito não cria conector personalizado. Em workspace Business ou Enterprise o admin precisa liberar antes, em Permissões e funções. #### Codex 1. Crie ou edite ~/.codex/config.toml, para valer em todas as sessões, ou .codex/config.toml na raiz de um projeto. 2. Rode codex mcp login notaguard e conclua o login do NotaGuard no navegador. Arquivo: `~/.codex/config.toml` ```toml [mcp_servers.notaguard] enabled = true url = "https://mcp.notaguard.com.br" ``` Sem bloco de headers no arquivo, o Codex usa OAuth, então não existe chave para guardar. Em config.toml de projeto ele só carrega o servidor com trust_level = "trusted". A extensão de VS Code do Codex lê o mesmo arquivo, mas tem bug aberto de não enxergar servidores remotos que funcionam no CLI. #### Qualquer outro cliente 1. Aponte o cliente para https://mcp.notaguard.com.br. 2. Escolha o transporte Streamable HTTP. 3. Deixe o login por conta do OAuth: o servidor aceita registro dinâmico, então não há chave nem segredo para cadastrar antes. ## Permissões No primeiro acesso o NotaGuard mostra a tela de permissões. Consultar e organizar é sempre concedida; as outras três você marca ou não. - **Consultar e organizar notas e relatórios** (`leitura`): Notas fiscais, análises, situação da empresa e etiquetas. Concedida sempre, sem caixa de seleção. Inclui criar e aplicar etiqueta, que é a única escrita desse escopo. - **Preparar rascunhos de NFS-e** (`rascunho`): O assistente monta a nota e para. A revisão e a emissão ficam na tela de rascunhos do painel. É a rédea curta de quem quer IA preparando sem emitir. - **Emitir NFS-e** (`emissao`): Prepara rascunhos e emite na SEFAZ em nome da empresa. Inclui a permissão de rascunho. - **Manifestar NF-e na SEFAZ** (`manifestacao`): Ciência, confirmação, desconhecimento ou operação não realizada das notas recebidas. Para revogar: no painel, em Minha conta, Segurança, na lista de aplicativos conectados. Revogar corta o acesso na hora. Quem conectou antes de agosto de 2026 continua com acesso só de leitura: a tela de permissões não reaparece enquanto a autorização estiver válida. Para usar emissão ou manifestação, revogue e conecte de novo marcando as permissões. ## Planos e limite de uso Incluso no Professional e no Enterprise. No Basic e no Standard, entra pelo adicional MCP + API, por R$ 19,90 por mês, contratado na assinatura dentro do painel; o mesmo adicional libera a API REST de consulta. Durante o teste grátis de 7 dias o acesso já vem liberado. O limite é por minuto e por usuário, separado do limite das chaves de API. - Teste grátis: 10 chamadas por minuto - Basic: 20 chamadas por minuto - Standard: 30 chamadas por minuto - Professional e Enterprise: 60 chamadas por minuto ## As 27 ferramentas | Ferramenta | Grupo | Permissão | O que faz | |---|---|---|---| | `listar_empresas` | Contexto | leitura | Lista as empresas da conta e devolve o id que todas as outras tools exigem. | | `diagnostico_empresa` | Contexto | leitura | Situação da empresa numa resposta: monitoramento, certificado, plano e uso, franquia de emissão e ciências pendentes, com os links do painel. | | `resumo_notas` | Notas | leitura | Totais do período, em quantidade e valor. É a tool de "quanto recebi em julho", em vez de somar página por página. | | `buscar_notas` | Notas | leitura | Lista notas por filtro estruturado: período, tipo, status, parceiro, valor, etiqueta. Paginação por cursor. | | `buscar_notas_por_texto` | Notas | leitura | Busca dentro do XML, no cabeçalho e nos itens. Acha a nota pelo produto, pelo serviço ou por qualquer texto livre. | | `obter_nota` | Notas | leitura | Uma nota em detalhe: itens, tributos, eventos registrados na SEFAZ e etiquetas. | | `obter_xml_nota` | Notas | leitura | XML autorizado de uma nota. Vem no corpo da resposta e, acima de 300 KB, como link. | | `listar_etiquetas` | Notas | leitura | Etiquetas existentes na empresa. | | `exportar_notas` | Notas | leitura | Abre uma exportação em lote de XML ou dados e devolve o protocolo para acompanhar. | | `consultar_exportacao` | Notas | leitura | Estado de uma exportação e o link do arquivo quando fica pronta. | | `gerenciar_etiqueta` | Etiquetas | leitura | Cria, renomeia ou remove uma etiqueta. | | `etiquetar_nota` | Etiquetas | leitura | Aplica ou tira uma etiqueta de uma nota. | | `catalogo_analise` | Análise | leitura | Dimensões, medidas e filtros disponíveis. O assistente consulta antes de montar um corte livre. | | `analisar_notas` | Análise | leitura | Corte livre sobre o acervo: agrupa por dimensão, aplica medida e filtro. Análise de imposto exige período. | | `painel_fiscal` | Análise | leitura | Dez painéis prontos: gasto, tributos, fornecedores, produtos, serviços, logística, geografia, parceiros, reforma tributária e alertas fiscais. | | `contas_a_pagar` | Análise | leitura | Duplicatas, vencimentos e formas de pagamento extraídos do XML das NF-e recebidas. | | `notas_para_manifestar` | Compliance | leitura | Notas dentro da janela de ciência (10 dias) e sem manifestação conclusiva (90 dias), dizendo se a ciência automática está ligada. | | `manifestar_notas` | Manifestação | manifestacao | Registra ciência, confirmação, desconhecimento ou operação não realizada na SEFAZ. Sai em duas etapas: prévia e confirmação por código. | | `contexto_emissao_nfse` | Emissão de NFS-e | leitura | O que a empresa tem para emitir: requisitos atendidos, séries, modelos salvos e clientes cadastrados. | | `detalhar_modelo_nfse` | Emissão de NFS-e | leitura | Um modelo em detalhe, com o guia de preenchimento campo a campo, avaliado ao vivo contra as regras da SEFAZ. | | `consultar_codigo_tributacao_nfse` | Emissão de NFS-e | leitura | Candidatos de código de tributação para você escolher. A tool não decide o código no seu lugar. | | `listar_rascunhos_nfse` | Emissão de NFS-e | leitura | Rascunhos abertos que o assistente criou. | | `preparar_nfse` | Emissão de NFS-e | rascunho | Cria rascunhos de NFS-e, um por variação, até 50 de uma vez. Nada vai à SEFAZ nesta etapa. | | `descartar_rascunho` | Emissão de NFS-e | rascunho | Descarta um rascunho aberto criado pelo assistente. | | `gerenciar_modelo_nfse` | Emissão de NFS-e | emissao | Cria, edita, desativa ou reativa modelo de serviço e de valores. Editar muda as próximas emissões de todo mundo na empresa. | | `emitir_nfse` | Emissão de NFS-e | emissao | Emite os rascunhos na SEFAZ. Duas etapas: prévia com valor, ambiente e franquia, e confirmação por código. | | `verificar_municipio_nfse` | NFS-e | leitura | Diz se o município emite pelo Emissor Nacional, contra a lista oficial atualizada. É o que separa uma emissão que passa de uma que volta com E0039. | ### Prompts prontos - `resumo_fiscal_do_mes`: Fecha o mês da empresa: entradas, saídas, tributos e pendências. - `panorama_empresas`: Compara a situação de todas as empresas da conta lado a lado. ## Perguntas frequentes ### Como conecto o NotaGuard no Claude? Em Configurações, Conectores, Adicionar conector personalizado, cole https://mcp.notaguard.com.br. O Claude abre o login do NotaGuard e mostra as permissões antes de qualquer acesso. No Claude Code o comando é claude mcp add --transport http notaguard https://mcp.notaguard.com.br, seguido de /mcp para fazer o login. O mesmo endereço serve para Cursor, VS Code e qualquer outro cliente que fale MCP: a página tem o passo de cada um. ### Preciso instalar alguma coisa? Não. O servidor é remoto: o cliente fala com o endereço direto. Não existe pacote npm para instalar, não existe comando npx do NotaGuard, não existe binário para baixar e não existe chave de API para colar em arquivo de configuração. Se alguma instrução mandar rodar um npx, a instrução está errada. ### Quanto custa usar o MCP? Está incluso no Professional e no Enterprise. No Basic e no Standard entra pelo adicional MCP + API, por R$ 19,90 por mês, contratado na assinatura dentro do painel. O mesmo adicional libera a API REST de consulta. Durante o teste grátis de 7 dias o acesso já vem liberado. ### O assistente pode emitir nota fiscal sem eu ver? Só se você conceder a permissão de emissão, que não vem marcada. Sem ela o assistente lê, analisa e organiza, e no máximo prepara rascunhos, se você conceder a permissão de rascunho. Com a emissão concedida, a tool trabalha em duas etapas: primeiro devolve a prévia com valor, ambiente e franquia, e só emite quando recebe o código que a própria prévia gerou. O código vale 10 minutos e um rascunho editado depois da prévia é recusado. ### Conectei antes e as permissões de emissão não aparecem. Por quê? A tela de consentimento pula quando já existe uma autorização válida, então quem conectou antes de a emissão existir continua com acesso só de leitura. Revogue o aplicativo em Minha conta, Segurança, e conecte de novo marcando as permissões que quer. ### Funciona no ChatGPT e no Codex? Funciona nos dois. No ChatGPT é um conector personalizado, criado com o Modo desenvolvedor ligado, em conta Plus, Pro, Business, Enterprise ou Edu; o plano gratuito não cria conector personalizado. No Codex é uma entrada no config.toml mais o comando de login. O passo a passo dos dois está acima. ### O assistente enxerga as notas de todas as minhas empresas? A autorização é da sua conta, e cada chamada exige um id de empresa. O servidor confere, a cada chamada, se você é membro daquela empresa e se ela tem acesso ao MCP. ### Tem limite de uso? Sim, por minuto e por usuário: 10 chamadas no teste grátis, 20 no Basic, 30 no Standard e 60 no Professional e no Enterprise. O limite é separado do limite das chaves da API REST, então usar o MCP não consome a cota das suas integrações. ### Minha empresa bloqueia domínios novos na rede. O que peço para o TI? Liberar https://mcp.notaguard.com.br na saída HTTPS. É o único endereço que o cliente precisa alcançar. ### Como desconecto o assistente? No painel, em Minha conta, Segurança, na lista de aplicativos conectados. Revogar corta o acesso na hora: os tokens deixam de valer e as permissões concedidas são encerradas. --- - Planos: https://notaguard.com.br/planos - API REST de consulta: https://notaguard.com.br/desenvolvedores/api - Teste grátis: https://notaguard.com.br/teste-gratis - Contato: https://notaguard.com.br/contato