Servidor MCP para agentes de IA
Conecta Constaia a Claude Desktop, Claude Code, Cursor, VS Code o Windsurf con @constaia/mcp para validar y extraer datos de documentos desde un agente.
@constaia/mcp es un servidor Model Context Protocol (stdio) que da a tus
agentes de IA herramientas para validar, clasificar y extraer datos de documentos con Constaia. Le puedes pedir
cosas como: "¿Es ~/Descargas/dni.jpg un DNI español vigente? Dame el número y la fecha de nacimiento."
CONSTAIA_API_KEY=ck_test_... npx -y @constaia/mcpEmpieza con una clave de test
Con una clave ck_test_… no se gastan créditos y la respuesta depende del nombre del fichero
(dni_valid.jpg, dni_expired.jpg, blurry.jpg…). Ideal para probar el flujo con tu agente. Ver
Modo test.
Instalación
No hace falta instalar nada: los clientes MCP lo arrancan con npx -y @constaia/mcp. Si prefieres una
instalación global, el binario se llama constaia-mcp:
npm install -g @constaia/mcp
constaia-mcp --versionRequiere Node.js ≥ 18.
Variables de entorno
| Variable | |
|---|---|
CONSTAIA_API_KEY | Obligatoria. ck_live_… gasta créditos; ck_test_… es gratis y determinista. |
CONSTAIA_BASE_URL | Opcional. Por defecto https://api.constaia.com. |
CONSTAIA_ALLOWED_DIRS | Opcional pero recomendada. Directorios (separados por comas) desde los que el agente puede subir ficheros. |
Solo salen de tu equipo ficheros JPEG, PNG, WEBP, HEIC y PDF de hasta 20 MB; el resto se rechaza antes de
enviarse. Con CONSTAIA_ALLOWED_DIRS, una ruta fuera de esos directorios también se rechaza.
Herramientas
| Herramienta | Qué hace | Entradas |
|---|---|---|
analyze_document | Valida y extrae: tipo, veredicto, motivos, campos, checks y avisos. | file (ruta local o URL https://), expect (tipo o lista), checks (en snake_case, como la API), exports (xlsx, csv, json…), extract, language, metadata |
classify_document | Solo detecta el tipo (0,2 créditos). | file, expect opcional |
list_document_types | Catálogo de tipos con sus campos. | — |
get_analysis | Recupera un análisis anterior. | id (an_…) |
get_balance | Créditos disponibles, reservados y del plan gratis. | — |
Cada resultado incluye un resumen legible seguido del JSON completo que devuelve la API.
Configuración por cliente
Edita claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"constaia": {
"command": "npx",
"args": ["-y", "@constaia/mcp"],
"env": {
"CONSTAIA_API_KEY": "ck_test_...",
"CONSTAIA_ALLOWED_DIRS": "/Users/yo/Documentos/Docs"
}
}
}
}Reinicia Claude Desktop después de guardar.
Ejemplos de uso
- "Comprueba si
~/Docs/dni_valid.jpges un DNI o NIE vigente y cuyo titular sea María García López." - "Analiza las facturas de
~/Docs/facturasy exporta un Excel con número, fecha y total." - "¿El certificado médico
certificado.pdftiene menos de un año y está firmado y sellado?" - "¿Cuántos créditos me quedan?"
El agente decide qué herramienta usar y con qué expect y checks. Si el resultado es review, pídele que te
muestre los avisos: son señales, no prueba de fraude.
Uso programático
Para integrarlo en tu propio servidor MCP o con otro transporte:
import { createServer } from "@constaia/mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const server = createServer({
apiKey: process.env.CONSTAIA_API_KEY,
allowedDirs: ["/srv/documents"],
});
await server.connect(new StdioServerTransport());Privacidad
Los ficheros van directamente de tu equipo a la API de Constaia. Por defecto solo se guardan, cifrados, los que
necesitan revisión humana, y se borran al decidir; los demás se borran en cuanto termina el análisis. Usa CONSTAIA_ALLOWED_DIRS para que el agente no pueda leer fuera de las carpetas que
elijas, y una clave de test mientras pruebas. Más en Almacenamiento y privacidad.