Skip to content
Factum ParseFactum ParseFactum Parse

MCP Integration — Tool Reference

Tool factum_parse_text

Section titled “Tool factum_parse_text”

Parses direct text synchronously with zero-retention.

{
  "name": "factum_parse_text",
  "inputSchema": {
    "type": "object",
    "properties": {
      "text": { "type": "string", "description": "Document text to analyze" },
      "doc_type": {
        "type": "string",
        "enum": ["auto", "fattura", "f24", "generico"],
        "default": "auto"
      }
    },
    "required": ["text"]
  }
}

Output: ParseResponse with DocumentEnvelope v2 (schema_version, meta, payload).

Errors: 401 (missing key), 422 (empty text), 503 (PII sidecar down).

Tool factum_upload_document

Section titled “Tool factum_upload_document”

Upload a file (FatturaPA XML or PDF) for asynchronous processing.

{
  "name": "factum_upload_document",
  "inputSchema": {
    "type": "object",
    "properties": {
      "filename": { "type": "string", "description": "Filename (e.g. IT01234567890_2026.xml)" },
      "file": { "type": "string", "description": "Base64-encoded file content" }
    },
    "required": ["filename", "file"]
  }
}

Output: DocumentResponse (status done or processing with job_id for polling).

Errors: 401, 413 (> 10 MB), 415 (Content-Type), 422 (invalid XML).

Tool factum_status

Section titled “Tool factum_status”

Public liveness/status, no authentication required.

{
  "name": "factum_status",
  "inputSchema": { "type": "object", "properties": {} }
}

Output: { "status": "ok", "version": "...", "uptime_seconds": N }.

Guaranteed behavior (ZDR)

Section titled “Guaranteed behavior (ZDR)”
  • Text passed to factum_parse_text lives only in RAM for the duration of the request: never on disk, never in DB, never in logs.
  • The PII sidecar pseudonymizes before the LLM and restores the mapping after the response.
  • Nothing is explicitly retried by the agent if the tool returns 503 (privacy block): the server is intentionally fail-closed.