IA e MCP

Servidor MCP: a Sudrel no seu assistente de IA

O MCP (Model Context Protocol) é o padrão aberto que permite a um assistente de IA consultar sistemas externos. Com o servidor MCP da Sudrel, você pergunta em português e o assistente responde com os seus dados reais:

• "Quanto entrou de nota esse mês?"
• "Algum fornecedor parou de faturar pra gente?"
• "Me mostra as notas acima de R$ 5.000 de agosto"
• "Quanto já usei da franquia do plano?"

Situação: o pacote @sudrel/mcp-server está publicado no npm. Ele roda no seu computador (transporte stdio), então funciona em clientes que executam servidor MCP local, como o Claude Desktop. Assistentes que só aceitam servidor remoto (ChatGPT, Claude na web) ainda não são atendidos.

Instalação

Adicione ao arquivo de configuração do seu cliente MCP. No Claude Desktop, é o claude_desktop_config.json:

{
  "mcpServers": {
    "sudrel": {
      "command": "npx",
      "args": ["-y", "@sudrel/mcp-server"],
      "env": { "SUDREL_API_KEY": "sdr_live_..." }
    }
  }
}

Use uma chave de produção (sdr_live_): a chave de teste não lê documentos recebidos. Código aberto, licença MIT. SUDREL_API_URL (opcional) muda o endereço da API; o padrão é https://api.sudrel.com.br/api/v1.

O que o agente pode e não pode fazer

Ferramenta	O que faz	Lê	Escreve
consultar_conta	Nome, status e ambiente da conta ligada à chave	Sim	Não
consultar_consumo	Franquia usada no ciclo, saldo e excedente	Sim	Não
listar_empresas	CNPJs da conta e o estado de cada um	Sim	Não
detalhar_empresa	Detalhe de um CNPJ, incluindo certificado	Sim	Não
listar_documentos	NFS-e, NF-e e CT-e capturadas, com filtro de período, fornecedor, valor, tipo e papel	Sim	Não
detalhar_documento	Documento completo, com prestador, tomador, valores e tributos	Sim	Não
listar_notas_emitidas	NFS-e emitidas pela conta (API, planilha ou painel), com filtro de situação	Sim	Não
detalhar_nota_emitida	Nota emitida completa: linha do tempo, ajustes feitos pela Sudrel e, se rejeitada, a explicação com a correção	Sim	Não
listar_lotes	Lotes de emissão, com as contagens por situação	Sim	Não
detalhar_lote	Situação de um lote e quantas notas estão em cada situação	Sim	Não
listar_itens_lote	Linhas de um lote e o resultado de cada uma	Sim	Não
consultar_prontidao_emissao	Se a empresa pode emitir agora, item por item, com o que fazer em cada bloqueio	Sim	Não
listar_eventos_recentes	Log de eventos da conta (nota autorizada, rejeitada, cancelada, documento recebido...)	Sim	Não

Valores em listar_documentos são filtrados em centavos: R$ 1.500,00 é 150000. A própria descrição da ferramenta avisa isso ao modelo.

O agente não pode: emitir, validar, cancelar ou substituir nota, criar ou alterar empresa, enviar certificado, criar webhook, nem qualquer outra escrita.

Somente leitura, e isso é uma decisão de projeto

O servidor MCP da Sudrel não emite nota, não cancela, não cria empresa e não remove nada. Ele só lê. Os endpoints de escrita desta API existem e funcionam, mas nenhum deles é exposto ao agente.

O motivo é o modelo de ameaça do MCP. Um servidor MCP entrega as ferramentas a um modelo que decide sozinho quando chamá-las, a partir de texto que pode ter vindo de qualquer lugar, inclusive do conteúdo de um documento fiscal que a própria ferramenta acabou de trazer. A descrição do serviço de uma nota é texto livre que qualquer fornecedor escreve. Num servidor que sabe emitir nota, esse texto passa a ser uma superfície de injeção com consequência fiscal real.

Quem precisa automatizar emissão usa a API REST direto, com código que passa por revisão e por um deploy, e não por um modelo decidindo no meio de uma conversa.

Internamente, todo acesso do servidor MCP passa por uma única função que só faz GET. Expor escrita exigiria mudar essa função de propósito, e isso é o atrito que se quer.

Para quem escreve um agente sobre a API REST

• A especificação completa está em https://sudrel.com.br/docs/openapi.json (e /docs/openapi.yaml). Um resumo em texto, pensado para modelos, está em https://sudrel.com.br/docs/llms.txt.
• Operações de leitura (todo GET) são seguras de repetir. As de escrita (POST, PATCH, DELETE) têm efeito real; em POST /v1/nfse e POST /v1/lotes, use sempre Idempotency-Key e referencia.
• Faça o agente decidir por codigo e status, nunca por mensagem.
• Teste com a chave sdr_test_: nada do que ela emite tem valor fiscal.
• Siga as Regras de integração.