IA y MCP

Servidor MCP: Sudrel en tu asistente de IA

El MCP (Model Context Protocol) es el estándar abierto que permite a un asistente de IA consultar sistemas externos. Con el servidor MCP de Sudrel, preguntas en portugués y el asistente responde con tus datos reales:

• "Quanto entrou de nota esse mês?" (¿Cuánto entró en notas fiscales este mes?)
• "Algum fornecedor parou de faturar pra gente?" (¿Algún proveedor dejó de facturarnos?)
• "Me mostra as notas acima de R$ 5.000 de agosto" (Muéstrame las notas fiscales de más de R$ 5.000 de agosto)
• "Quanto já usei da franquia do plano?" (¿Cuánto ya usé de la franquicia del plan?)

Situación: el paquete @sudrel/mcp-server está publicado en npm. Se ejecuta en tu computadora (transporte stdio), así que funciona en clientes que ejecutan un servidor MCP local, como Claude Desktop. Los asistentes que solo aceptan servidor remoto (ChatGPT, Claude en la web) todavía no son compatibles.

Instalación

Agrégalo al archivo de configuración de tu cliente MCP. En Claude Desktop, es claude_desktop_config.json:

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

Usa una clave de producción (sdr_live_): la clave de prueba no lee documentos recibidos. Código abierto, licencia MIT. SUDREL_API_URL (opcional) cambia la dirección de la API; el valor predeterminado es https://api.sudrel.com.br/api/v1.

Qué puede y qué no puede hacer el agente

Herramienta	Qué hace	Lee	Escribe
consultar_conta	Nombre, status y entorno de la cuenta vinculada a la clave	Sí	No
consultar_consumo	Franquicia usada en el ciclo, saldo y excedente	Sí	No
listar_empresas	CNPJ de la cuenta y el estado de cada uno	Sí	No
detalhar_empresa	Detalle de un CNPJ, incluido el certificado	Sí	No
listar_documentos	NFS-e, NF-e y CT-e capturadas, con filtro de período, proveedor, valor, tipo y rol	Sí	No
detalhar_documento	Documento completo, con prestador, tomador, valores y tributos	Sí	No
listar_notas_emitidas	NFS-e emitidas por la cuenta (API, planilla o panel), con filtro de situación	Sí	No
detalhar_nota_emitida	Nota fiscal emitida completa: línea de tiempo, ajustes hechos por Sudrel y, si fue rechazada, la explicación con la corrección	Sí	No
listar_lotes	Lotes de emisión, con los conteos por situación	Sí	No
detalhar_lote	Situación de un lote y cuántas notas fiscales están en cada situación	Sí	No
listar_itens_lote	Líneas de un lote y el resultado de cada una	Sí	No
consultar_prontidao_emissao	Si la empresa puede emitir ahora, ítem por ítem, con qué hacer en cada bloqueo	Sí	No
listar_eventos_recentes	Log de eventos de la cuenta (nota fiscal autorizada, rechazada, cancelada, documento recibido...)	Sí	No

Los valores en listar_documentos se filtran en centavos: R$ 1.500,00 es 150000. La propia descripción de la herramienta se lo advierte al modelo.

El agente no puede: emitir, validar, cancelar ni sustituir una nota fiscal, crear ni modificar una empresa, enviar un certificado, crear un webhook, ni ninguna otra escritura.

Solo lectura, y es una decisión de diseño

El servidor MCP de Sudrel no emite notas fiscales, no cancela, no crea empresas y no elimina nada. Solo lee. Los endpoints de escritura de esta API existen y funcionan, pero ninguno se expone al agente.

El motivo es el modelo de amenazas del MCP. Un servidor MCP entrega las herramientas a un modelo que decide solo cuándo llamarlas, a partir de texto que puede venir de cualquier lugar, incluso del contenido de un documento fiscal que la propia herramienta acaba de traer. La descripción del servicio de una nota fiscal es texto libre que cualquier proveedor escribe. En un servidor que sabe emitir notas fiscales, ese texto se convierte en una superficie de inyección con consecuencia fiscal real.

Quien necesita automatizar la emisión usa la API REST directamente, con código que pasa por revisión y por un deploy, y no por un modelo que decide en medio de una conversación.

Internamente, todo acceso del servidor MCP pasa por una única función que solo hace GET. Exponer escritura exigiría cambiar esa función a propósito, y esa es la fricción que se busca.

Si escribes un agente sobre la API REST

• La especificación completa está en https://sudrel.com.br/docs/openapi.json (y /docs/openapi.yaml). Un resumen en texto, pensado para modelos, está en https://sudrel.com.br/docs/llms.txt.
• Las operaciones de lectura (todo GET) son seguras de repetir. Las de escritura (POST, PATCH, DELETE) tienen efecto real; en POST /v1/nfse y POST /v1/lotes, usa siempre Idempotency-Key y referencia.
• Haz que el agente decida por codigo y status, nunca por mensagem.
• Prueba con la clave sdr_test_: nada de lo que emite tiene valor fiscal.
• Sigue las Reglas de integración.