NormAPI

npx add-mcp 'https://normapi.com/mcp'

Endpoint e pacote

O servidor é executado hospedado neste endereço (HTTP Streamable) e como um pacote npm para clientes que iniciam servidores como um processo local (stdio). Ambos oferecem as mesmas ferramentas.

Hospedado

https://normapi.com/mcp

Local (stdio)

npx -y @normapi/mcp

Conectar

Clientes com conectores precisam apenas do endereço; na primeira vez que você gerar uma fatura, o cliente faz seu login na NormAPI com OAuth. Clientes com um arquivo de configuração podem usar sua chave de API como um cabeçalho.

• Claude (claude.ai e Desktop): Configurações → Conectores → Adicionar conector personalizado e cole o endereço.
• ChatGPT: no modo de desenvolvedor, crie um conector personalizado com este endereço e autenticação OAuth.

Claude Code

claude mcp add --transport http normapi https://normapi.com/mcp

# or with your key instead of OAuth:
claude mcp add --transport http normapi https://normapi.com/mcp \
  --header "Authorization: Bearer nk_live_…"

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "normapi": {
      "url": "https://normapi.com/mcp",
      "headers": { "Authorization": "Bearer nk_live_…" }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "normapi": { "type": "http", "url": "https://normapi.com/mcp" }
  }
}

Qualquer cliente stdio (por exemplo, claude_desktop_config.json)

{
  "mcpServers": {
    "normapi": {
      "command": "npx",
      "args": ["-y", "@normapi/mcp"],
      "env": { "NORMAPI_API_KEY": "nk_live_…" }
    }
  }
}

Ferramentas

Três ferramentas, cada uma com um resultado estruturado e uma versão em texto para modelos que leem apenas texto.

Ferramenta	O que faz	Conta
validate_invoice	Verifica um XRechnung (UBL ou CII, como texto) ou um PDF ZUGFeRD/Factur-X (base64) de acordo com as regras oficiais da KoSIT. Retorna o veredito, a versão do conjunto de regras e cada achado; cada achado de regra de negócio traz uma explicação: o que a regra exige, por que ela normalmente é acionada e como corrigi-la.	não
generate_invoice	Produz um XRechnung (UBL ou CII) ou um PDF ZUGFeRD a partir dos dados da fatura. Os totais são calculados no servidor com aritmética decimal, e o documento é validado antes de ser retornado. Dados que as regras não permitem são recusados com as regras violadas e como corrigir cada uma — e não são contabilizados.	sim, conta contra a cota
explain_rule	Explica uma regra pelo seu código (BR-DE-15, BR-CO-10, PEPPOL-EN16931-R010 …), com um link para sua página completa.	não

Login e chaves

Três formas de acesso, dependendo do cliente:

• OAuth 2.1 (Claude, ChatGPT e outros conectores): você faz login na NormAPI e permite a conexão. Ela recebe uma chave de API própria, nomeada após o aplicativo (mcp-claude-…). Revogue essa chave em Chaves de API e o aplicativo é desconectado imediatamente.
• Uma chave de API como cabeçalho (Claude Code, Cursor, VS Code): Authorization: Bearer nk_live_… — a mesma chave da API REST.
• stdio: a chave na variável de ambiente NORMAPI_API_KEY.

Criar uma chave de API

Limites e privacidade

As mesmas regras da API REST:

• Documentos de até 5 MB. Chamadas sem chave estão sob os limites anônimos da API; chamadas com chave, sob os limites dessa chave.
• Cada fatura gerada conta contra a cota mensal (25 gratuitas); validação nunca conta.
• As faturas são processadas em memória e nunca armazenadas — nem pelo servidor MCP.
• Validação técnica, não aconselhamento fiscal ou jurídico.