MCP server

Aletheia ships an MCP (Model Context Protocol) server so an AI agent can score applicant documents for fraud, pull back auditable findings, and generate PDF reports through typed tool calls. The server runs locally over stdio and talks to your Aletheia instance over HTTPS using a bearer token.

The verdict itself stays deterministic and rule-based, the agent only orchestrates the calls; it never decides the verdict.

Install

pip install idcanopy-aletheia-mcp

Configure

Variable	Value
`FORENSIC_API_TOKEN`	Your bearer token (from onboarding). Env only, never commit it.
`FORENSIC_API_BASE_URL`	See Environments

Point your MCP-capable client's config at the idcanopy-aletheia-mcp command with those two environment variables set.

Tools

Tool	What it does
`analyze_documents`	One-shot, stateless analysis of document files, returns verdict and findings
`create_applicant`	Create a persistent applicant record
`upload_documents`	Attach documents to an applicant
`get_applicant_result`	Analyze an applicant's stored documents and return the result
`get_findings`	Re-read a stored result without re-analyzing
`analyze_batch`	Submit an async batch job over many applicants
`get_batch_status`	Poll a batch job
`get_report`	Generate the branded PDF report to a local file

analyze_documents and get_applicant_result emit progress notifications on long (60s+) multi-document calls when the client supplies a progress token.

Authentication

The bearer token is read from FORENSIC_API_TOKEN only. It is never logged, echoed, or returned by any tool, and is never accepted as a tool argument. Outbound result webhooks are HMAC-signed - see Webhooks before trusting any callback.

Error handling

Every HTTP failure is mapped onto the public error contract and surfaced as a structured error map, never a raw HTTP or HTML body: 4xx/5xx follow the ProblemDetails shape (detail, plus trace_id on stateless /analyze 5xx responses); 429 follows RateLimitError (code: "rate_limit_exceeded" plus retry_after seconds).