MCP server for AI agents
Connect Constaia to Claude Desktop, Claude Code, Cursor, VS Code or Windsurf with @constaia/mcp to validate documents and extract data from an agent.
@constaia/mcp is a Model Context Protocol server (stdio) that gives your AI
agents tools to validate, classify and extract data from documents with Constaia. You can ask things like:
"Is ~/Downloads/id.jpg a valid Spanish DNI? Give me the number and the date of birth."
CONSTAIA_API_KEY=ck_test_... npx -y @constaia/mcpStart with a test key
A ck_test_… key spends no credits and answers by file name (dni_valid.jpg, dni_expired.jpg,
blurry.jpg…). Ideal to try the flow with your agent. See Test mode.
Installation
Nothing to install: MCP clients start it with npx -y @constaia/mcp. If you prefer a global install, the binary
is called constaia-mcp:
npm install -g @constaia/mcp
constaia-mcp --versionRequires Node.js ≥ 18.
Environment variables
| Variable | |
|---|---|
CONSTAIA_API_KEY | Required. ck_live_… spends credits; ck_test_… is free and deterministic. |
CONSTAIA_BASE_URL | Optional. Defaults to https://api.constaia.com. |
CONSTAIA_ALLOWED_DIRS | Optional but recommended. Comma-separated directories the agent may upload files from. |
Only JPEG, PNG, WEBP, HEIC and PDF files up to 20 MB leave your machine; anything else is refused before being
sent. With CONSTAIA_ALLOWED_DIRS, a path outside those directories is refused too.
Tools
| Tool | What it does | Inputs |
|---|---|---|
analyze_document | Validates and extracts: type, verdict, reasons, fields, checks and warnings. | file (local path or https:// URL), expect (type or list), checks (snake_case, like the API), exports (xlsx, csv, json…), extract, language, metadata |
classify_document | Only detects the type (0.2 credits). | file, optional expect |
list_document_types | Type catalogue with fields. | — |
get_analysis | Fetches a previous analysis. | id (an_…) |
get_balance | Available, reserved and free-tier credits. | — |
Every result has a readable summary followed by the full JSON returned by the API.
Client configuration
Edit 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/me/Documents/Docs"
}
}
}
}Restart Claude Desktop after saving.
Example prompts
- "Check whether
~/Docs/dni_valid.jpgis a valid DNI or NIE whose holder is María García López." - "Analyze the invoices in
~/Docs/invoicesand export an Excel file with number, date and total." - "Is the medical certificate
certificate.pdfless than a year old, signed and stamped?" - "How many credits do I have left?"
The agent decides which tool to use and with which expect and checks. If the result is review, ask it to show
you the warnings: they are signals, not proof of fraud.
Programmatic use
To embed it in your own MCP server or use another transport:
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());Privacy
Files go straight from your machine to the Constaia API. By default they are deleted as soon as the analysis
finishes (storage: "none"). Use CONSTAIA_ALLOWED_DIRS so the agent can't read outside the folders you choose,
and a test key while you experiment. More in Storage and privacy.