MCP Integration — Agent Setup

Context

Factum Parse is designed as document intelligence infrastructure for B2B and AI Agents: an agent (Claude Code, Cursor, custom tooling) should be able to invoke structured invoice/F24 extraction directly from its tool loop, without going through a UI.

The target contract follows the Model Context Protocol (stdio/HTTP+SSE transport), with an MCP server exposing the Factum Parse API as tools.

Planned server structure

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

Planned tools

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

Agent configuration (Claude Code)

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

Backend dependencies

The MCP server only requires what is already in production:

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

No new backend features: the MCP is a client wrapper around the existing API.