MCP Integration — Agent Setup

Contesto

Factum Parse è pensato come infrastruttura di intelligence documentale per B2B e AI Agents: un agente (Claude Code, Cursor, custom tooling) deve poter invocare l’estrazione strutturata di fatture/F24 direttamente dal suo tool loop, senza passare per un’UI.

Il contratto target segue il Model Context Protocol (transport stdio/HTTP+SSE), con un server MCP che espone l’API Factum Parse come tool.

Struttura prevista del server

factum-mcp/
├── package.json
├── src/
│   ├── index.ts          ← entrypoint MCP (stdio server)
│   ├── tools/
│   │   ├── parse.ts      ← tool `factum_parse_text`
│   │   ├── upload.ts     ← tool `factum_upload_document`
│   │   └── status.ts     ← tool `factum_status`
│   └── api/
│       └── client.ts     ← client HTTP verso https://api.factum.pyragogy.org
└── README.md

Tool previsti

Tool	Input	Output
`factum_parse_text`	`text`, `doc_type?`	`DocumentEnvelope` v2
`factum_upload_document`	`file` (XML/PDF), `filename`	`DocumentResponse`
`factum_status`	—	status page pubblica

Configurazione agente (Claude Code)

{
  "mcpServers": {
    "factum": {
      "command": "npx",
      "args": ["-y", "factum-mcp"],
      "env": { "FACTUM_API_KEY": "..." }
    }
  }
}

Dipendenze dal backend

Il server MCP richiede solo ciò che è già in produzione:

POST /v1/parse (auth X-API-Key) — input testuale
POST /v1/uploads — file upload
GET /status — health pubblica

Nessuna nuova feature backend: il MCP è un client wrapper dell’API esistente.