IDCanopy Developers

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-mcp

Published on PyPI as idcanopy-aletheia-mcp. Gives you the idcanopy-aletheia-mcp console script.

2. Configure your agent

You need two values:

VariableValue
FORENSIC_API_TOKENYour bearer token (from onboarding). Env only, never commit it.
FORENSIC_API_BASE_URLhttps://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

ToolWhat it does
analyze_documentsOne-shot, stateless analysis of document files, returns verdict and findings
create_applicantCreate a persistent applicant record
upload_documentsAttach documents to an applicant
get_applicant_resultAnalyze an applicant's stored documents and return the result
get_findingsRe-read a stored result without re-analyzing
analyze_batchSubmit an async batch job over many applicants
get_batch_statusPoll a batch job
get_reportGenerate 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-ID header. 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_TOKEN only. 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) plus http_status, and trace_id on stateless /analyze 5xx responses (quote it in support tickets).
  • 429 follows RateLimitError: code: "rate_limit_exceeded" plus retry_after (seconds) mirrored from the Retry-After header; 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_statusCause and fix
(none) FORENSIC_API_TOKEN is not setExport the token in the client's env block.
401Token wrong or expired; re-check your onboarding credentials.
409 on report/resultNo analysis has run yet for that applicant.
400 on analyze_batchBatch smaller than your tenant's async threshold; use get_applicant_result per applicant.
404 on a job/applicantWrong id, or it belongs to another tenant (isolation).
429Rate limited; honour error.retry_after (seconds) and retry.

On this page