MCP y asistentes

El servidor MCP de Ecuafact expone esta API a asistentes compatibles con Model Context Protocol (Claude Desktop, Cursor, VS Code). El asistente puede consultar contexto, emitir comprobantes y reenviar correos en tu nombre usando la misma API Key y los mismos permisos que ya tienes.

El servidor no almacena credenciales: reenvia la API Key que le entregas en cada peticion y aplica la autorizacion del API.

Endpoint#

El servidor usa Streamable HTTP (remoto). Cada peticion incluye tu API Key en la cabecera X-Api-Key; sin ella responde 401.

Ambiente	Endpoint
Pruebas	`https://mcp-staging.mynexusapi.com/mcp`
Produccion	`https://mcp.mynexusapi.com/mcp`

Configuracion del cliente#

Registra el servidor con el tipo http y tu API Key. Usa el endpoint de produccion https://mcp.mynexusapi.com/mcp; para pruebas, https://mcp-staging.mynexusapi.com/mcp.

{
  "mcpServers": {
    "ecuafact": {
      "type": "http",
      "url": "https://mcp.mynexusapi.com/mcp",
      "headers": { "X-Api-Key": "tu-api-key" }
    }
  }
}

En VS Code el archivo es .vscode/mcp.json y la clave raiz es servers:

{
  "servers": {
    "ecuafact": {
      "type": "http",
      "url": "https://mcp.mynexusapi.com/mcp",
      "headers": { "X-Api-Key": "tu-api-key" }
    }
  }
}

Herramientas#

Lectura:

Herramienta	Para que sirve
`obtener_contexto`	Cliente y contribuyentes habilitados
`obtener_consumo`	Cupo disponible y paquetes
`consultar_operacion`	Estado de una emision por `idOperacion`
`listar_emitidos`	Comprobantes emitidos (paginado y con filtros)
`descargar_archivo`	RIDE (PDF) o XML de un comprobante
`validar_identificacion`	Formato de cedula, RUC o pasaporte
`consultar_contribuyente`	Catastro del SRI por identificacion
`buscar_contribuyentes`	Catastro del SRI por nombre
`listar_establecimientos`	Establecimientos de un RUC
`decodificar_clave_acceso`	Segmentos de una clave de acceso
`leer_catalogo`	Catalogos del SRI

Escritura:

Herramienta	Para que sirve
`emitir_comprobante`	Emite un comprobante
`reenviar_correo`	Reenvia el PDF y el XML por correo

Emision desde un asistente#

emitir_comprobante exige confirmar=true y una idempotencyKey estable (reutilizala en reintentos). El cuerpo es la Estructura del comprobante; cada tipo tiene su pagina:

Tipo	Guia
Factura	emision-01
Nota de credito	emision-04
Comprobante de retencion	emision-07

Las reglas de emision son las mismas de la API: revisa Primeros pasos y Errores.

Skill#

Si tu asistente integra el API sin el MCP, descarga el skill para asistentes de IA.

Seguridad#

Usa una API Key con el alcance minimo necesario.
El servidor reenvia la clave por peticion; no la guarda ni la registra en logs.
Valida el header Origin y restringe los hosts permitidos en el servidor.
Para pruebas, apunta Ecuafact:BaseUrl al ambiente de pruebas.