MCP server
Drive Aletheia from an AI agent over the Model Context Protocol
Aletheia ships an MCP (Model Context Protocol) server so an AI agent (Claude Desktop, Cline, Codex, or any MCP client) 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 Aletheia 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.
1. Install
pip install idcanopy-aletheia-mcpPublished on PyPI as idcanopy-aletheia-mcp.
Gives you the idcanopy-aletheia-mcp console script.
2. Configure your agent
You need two values:
| Variable | Value |
|---|---|
FORENSIC_API_TOKEN | Your bearer token (from onboarding). Env only, never commit it. |
FORENSIC_API_BASE_URL | https://aletheia.api-umbrella.io (production; a sandbox tenant gets a suffixed host, see Environments) |
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or
%APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"forensic": {
"command": "idcanopy-aletheia-mcp",
"env": {
"FORENSIC_API_TOKEN": "<your-bearer>",
"FORENSIC_API_BASE_URL": "https://aletheia.api-umbrella.io"
}
}
}
}Cline (VS Code)
In Cline's MCP settings (cline_mcp_settings.json):
{
"mcpServers": {
"forensic": {
"command": "idcanopy-aletheia-mcp",
"env": {
"FORENSIC_API_TOKEN": "<your-bearer>",
"FORENSIC_API_BASE_URL": "https://aletheia.api-umbrella.io"
}
}
}
}Codex
{
"servers": {
"forensic": {
"command": "idcanopy-aletheia-mcp",
"transport": "stdio",
"env": {
"FORENSIC_API_TOKEN": "<your-bearer>",
"FORENSIC_API_BASE_URL": "https://aletheia.api-umbrella.io"
}
}
}
}Restart the client; the forensic tools appear in the tool list.
3. 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 (60 s and
more) multi-document calls when the client supplies a progress token.
4. Example
Agent call:
{
"tool": "analyze_documents",
"arguments": {
"file_paths": [
"/cases/applicant-7/payslip.pdf",
"/cases/applicant-7/bank_statement.pdf"
]
}
}Result:
{
"verdict": "REJECT",
"reason_codes": ["ANONYMOUS_CREDIT_CLUSTER"],
"override_rules_fired": ["AML2", "F13"],
"verdict_explanation": "Rule AML2 (Anonymous SEPA-Gutschrift cluster, CRITICAL, REJECT) fired on: ['anonymous_credit_cluster']; Rule F13: verdict floor ESCALATE triggered by 4 finding(s) at HIGH+"
}Verdicts are one of REJECT, ESCALATE, PENDING, CONDITIONAL, PASS, each traceable to the
named rules that fired. The advisory score (advisory_score, 0 to 100) is a secondary signal only
and never drives the verdict.
On error, a tool returns a structured map under error rather than a raw HTTP body, see
Error handling:
{
"error": {
"http_status": 409,
"detail": "no analysis has run for this applicant yet",
"stage": "analyze"
}
}5. Authentication and security
The API contract defines two modes; the MCP server is configured for one of them via its env
block:
- Mode A, production multi-tenant. A per-tenant API key
(
Authorization: Bearer fsk_<prefix>_<secret>); the tenant identity is derived from the key, so no tenant header is sent. Mutual TLS at the reverse proxy is available as an optional connection-level hardening, not required by default, see mTLS. - Mode B, single-tenant compatibility. A shared service bearer token paired with an
X-Tenant-IDheader. The header is ignored in Mode A.
Set FORENSIC_API_TOKEN to whichever bearer your onboarding issues. In Mode B, the MCP host also
sets the tenant selector via your client's env.
- The bearer token is read from
FORENSIC_API_TOKENonly. It is never logged, echoed, or returned by any tool, and is never accepted as a tool argument. - Outbound result webhooks (
event_type: "analysis_completed") are HMAC-signed; verify them per Webhooks before trusting any callback.
6. 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
ProblemDetails:detail(always present) plushttp_status, andtrace_idon stateless/analyze5xx responses (quote it in support tickets). - 429 follows
RateLimitError:code: "rate_limit_exceeded"plusretry_after(seconds) mirrored from theRetry-Afterheader; back off and retry.
{ "error": { "http_status": 429, "code": "rate_limit_exceeded", "retry_after": 12 } }7. Troubleshooting
Each row below is the error.http_status you will see in the structured error map.
http_status | Cause and fix |
|---|---|
(none) FORENSIC_API_TOKEN is not set | Export the token in the client's env block. |
401 | Token wrong or expired; re-check your onboarding credentials. |
409 on report/result | No analysis has run yet for that applicant. |
400 on analyze_batch | Batch smaller than your tenant's async threshold; use get_applicant_result per applicant. |
404 on a job/applicant | Wrong id, or it belongs to another tenant (isolation). |
429 | Rate limited; honour error.retry_after (seconds) and retry. |