Sifende MCP Server

@sifende/mcp

Servidor MCP oficial de Sifende. Conecta Claude, Cursor y otros clientes MCP a tu cuenta de Sifende para que puedas pedir en lenguaje natural lo que hoy hacés con la API: consultar documentos electrónicos de SIFEN, descargar el KuDE, buscar un RUC en el padrón y, si lo habilitás, emitir facturas, notas y eventos.

• Corre en tu máquina, por stdio, con tu propia API key. No hay servidor intermedio ni se envía nada a terceros.
• Arranca en solo lectura. Para emitir tenés que habilitarlo con una variable.
• Usa el SDK oficial @sifende/sdk, con los mismos reintentos seguros, idempotencia y cálculo de totales que la API.

Primeros pasos

Necesitás Node.js 22.18 o superior y un cliente MCP. No hace falta instalar nada: el cliente ejecuta el servidor con npx.

1. Creá una API key de Sandbox

En el panel de Sifende, entrá a API Keys → Crear API Key y creá una de Sandbox: empieza con sk_sandbox_ (guía). Con ella podés emitir sin enviar nada a SIFEN.

2. Agregá el servidor a tu cliente

Claude Code

claude mcp add sifende --env SIFENDE_API_KEY=sk_sandbox_... -- npx -y @sifende/mcp

Claude Desktop. Abrí Configuración → Desarrollador → Editar configuración, agregá este bloque a claude_desktop_config.json y reiniciá Claude Desktop:

{
  "mcpServers": {
    "sifende": {
      "command": "npx",
      "args": ["-y", "@sifende/mcp"],
      "env": {
        "SIFENDE_API_KEY": "sk_sandbox_..."
      }
    }
  }
}

Cursor. El mismo bloque va en ~/.cursor/mcp.json, o en .cursor/mcp.json para un solo proyecto. También sirve para otros clientes con el formato mcpServers (Windsurf, Cline, Zed con su variante, etc.).

3. Probá una consulta

¿Con qué ambiente estás conectado y cuántos documentos me quedan en el plan?

El modelo llama a informacion_servidor y consultar_consumo_plan. Si responde "Sandbox", ya está funcionando.

4. Emití tu primera factura de prueba

Para que el modelo pueda emitir, agregá SIFENDE_MCP_ALLOW_WRITE=true al bloque env y reiniciá el cliente:

"env": {
  "SIFENDE_API_KEY": "sk_sandbox_...",
  "SIFENDE_MCP_ALLOW_WRITE": "true"
}

En Claude Code, volvé a agregar el servidor con --env SIFENDE_MCP_ALLOW_WRITE=true (antes borralo con claude mcp remove sifende).

Después pedile:

Emití una factura al contado por 2 remeras a 150.000 Gs y un envío de 25.000 Gs, IVA 10%, para Juan Pérez, cédula 1234567. Cuando esté aprobada, bajame el KuDE.

El modelo calcula el total con calcular_totales, revisa los valores válidos con listar_enumeraciones, emite, consulta el estado hasta que SIFEN lo aprueba y guarda el PDF. Tu cliente te va a pedir confirmación antes de emitir.

Ambientes

El prefijo de la API key decide el ambiente. No hay otra URL ni otra configuración.

Para probar eventos, usá una API key sk_test_. Para saber con qué ambiente está conectado el servidor, preguntale al modelo o llamá a informacion_servidor.

Qué le podés pedir

Consultas (siempre disponibles):

¿En qué estado está el documento con CDC 01800123450010010000001...?

Buscá el RUC 80012345 en el padrón y decime la razón social.

Bajame el KuDE del documento 01800123450010010000001...

¿Qué códigos de unidad de medida acepta SIFEN?

Con la escritura habilitada:

Cancelá la factura con CDC 01800123450010010000001..., el cliente la rechazó.

Inutilizá las facturas 50 a 60 del timbrado 12345678, establecimiento 001, punto 001. Se saltaron por un error del sistema.

Hacé una nota de crédito por la devolución de una de las remeras de la factura anterior.

Antes de usar sk_live_

Con una API key sk_live_, cada emisión es un documento fiscal real a nombre de tu contribuyente.

• Supervisá cada operación. Un modelo puede equivocarse en un importe, un receptor o un tipo de documento. Un documento aprobado por SIFEN solo se deshace con una cancelación dentro de las 48 horas (facturas) o 168 horas (notas).
• Revisá los datos antes de aceptar una herramienta de escritura. Los clientes MCP piden confirmación por herramienta. No la desactives con sk_live_.
• Dejá SIFENDE_MCP_ALLOW_WRITE apagado cuando solo necesites consultar. Al arrancar con escritura habilitada y sk_live_, el servidor escribe una advertencia en stderr.
• Tratá la API key como una contraseña. Queda en texto plano en la configuración del cliente: no la subas a un repositorio.
• Corré el servidor solo en tu máquina. No lo expongas por red ni lo incluyas en una app que distribuyas.

Referencia

Variables de entorno

Herramientas de lectura

Siempre disponibles.

Herramientas de escritura

Solo aparecen con SIFENDE_MCP_ALLOW_WRITE=true. Con una API key sk_sandbox_ aparece solo emitir_documento, porque Sandbox no admite eventos.

emitir_documento y nominar_documento no se marcan como destructivas porque solo agregan: no modifican ni borran lo que ya está registrado. Aun así no tienen vuelta atrás (un documento emitido solo se anula con una cancelación dentro del plazo), y con una API key sk_live_ las cuatro descripciones le advierten al modelo que registran operaciones fiscales reales y que confirme los datos con el usuario.

Recursos

Errores

Los errores de la API (Problem Details, RFC 9457) le llegan al modelo como texto legible: el código, el detalle, cada campo inválido, los valores aceptados cuando falla una enumeración, el traceId para soporte y el enlace a la documentación del error.

Si se corta la conexión al emitir o registrar un evento, no se sabe si la operación se hizo. El mensaje incluye la idempotencyKey usada: si el modelo repite la llamada con esa misma idempotencyKey, recibe el resultado original y no se duplica el documento. emitir_documento y los eventos siempre devuelven la idempotencyKey que usaron.

Desarrollo

git clone https://github.com/ithdev/sifende-mcp
cd sifende-mcp
npm ci
npm run lint && npm run typecheck && npm test && npm run build

Los tests levantan el servidor MCP en memoria y simulan la API con un fetch falso, sin llamadas de red.

Probarlo con el Inspector

# Listar las herramientas
npx @modelcontextprotocol/inspector --cli -e SIFENDE_API_KEY=sk_sandbox_... node dist/index.mjs --method tools/list

# Llamar una herramienta
npx @modelcontextprotocol/inspector --cli -e SIFENDE_API_KEY=sk_sandbox_... node dist/index.mjs \
  --method tools/call --tool-name listar_enumeraciones --tool-arg nombre=tipoPago

# Interfaz web. El Inspector no hereda el entorno: pasá la API key en la interfaz o con -e.
SIFENDE_API_KEY=sk_sandbox_... npm run inspector

Publicar una versión

1. Subí la versión en package.json, en src/version.ts y en los dos campos version de server.json. Los tests fallan si no coinciden.
2. Hacé commit, push a main y esperá a que pase la CI.
3. Creá un GitHub Release con el tag vX.Y.Z de esa versión.

El workflow release.yml publica en npm y después en el MCP Registry. Necesita dos cosas configuradas una sola vez:

• npm: trusted publishing para @sifende/mcp con el workflow release.yml y el environment npm. No usa token.
• MCP Registry: el secret MCP_PRIVATE_KEY en el environment mcp-registry, que solo admite tags v*. Es la clave privada ed25519 cuya clave pública está en el registro TXT del apex de sifende.com.py (v=MCPv1; k=ed25519; p=...). Así se verifica el nombre py.com.sifende/mcp (sifende.com.py al revés).

MCP_PRIVATE_KEY va como los 32 bytes de la clave en hexadecimal. Para cargarla desde un archivo PEM:

openssl pkey -in clave-ed25519.pem -outform DER | tail -c 32 | xxd -p -c 64 \
  | tr -d "\n" | gh secret set MCP_PRIVATE_KEY --env mcp-registry --repo ithdev/sifende-mcp

Si el job del Registry falla, se puede publicar a mano desde la raíz del repo, con la versión ya publicada en npm:

mcp-publisher validate
mcp-publisher login dns --domain sifende.com.py --private-key "$MCP_PRIVATE_KEY"
mcp-publisher publish

Licencia

Apache 2.0. Copyright 2026 ITH E.A.S.; ver NOTICE.