mdfi.ai Docs

Quickstart

Set up mdfi in your coding agent, read a first document, and see what the agent gets back.

mdfi converts PDFs (scans included), Word, PowerPoint, Excel, HTML, email, image and text files into clean markdown, page by page, with a quality score for every page and a mark on anything it is unsure about. Your coding agent (Claude Code, Cursor or another MCP client) reads it through the mdfi-connect connector: the outline first, then only the pages it needs.

Choose a plan

mdfi has no free plan. Sign up on the mdfi dashboard, confirm your email address, then press Choose Starter or Choose Pro on the Billing page and pay through Stripe Checkout. Pricing lists what each plan includes and how pages are counted.

Get your API key

Stripe then returns you to the dashboard, which says Payment received (or, while Stripe is still confirming, "Your payment is being confirmed"; refresh the page shortly). Its Connect your agent link opens the Connect page. On your first visit, that page creates a key named default and puts it into its install snippets. It is shown once: copy it before you leave the page. If you lose it, use Create new key on the same page (within your plan's key limit), which also shows the new key once, and revoke the lost one: until you do, it stays active and counts toward the limit.

Install the connector

The connector runs with uvx, which comes with uv. Replace YOUR_MDFI_KEY with your key, or copy the snippets from the Connect page, which has it filled in on your first visit.

Claude Code: run this in your project's folder, then start a new Claude Code session there.

claude mcp add mdfi --env MDFI_API_KEY=YOUR_MDFI_KEY --env MDFI_API_URL=https://api.mdfi.ai -- uvx mdfi-connect

Cursor: add the mdfi entry to mcpServers in ~/.cursor/mcp.json, creating the file if it does not exist.

{
  "mcpServers": {
    "mdfi": {
      "command": "uvx",
      "args": ["mdfi-connect"],
      "env": {
        "MDFI_API_KEY": "YOUR_MDFI_KEY",
        "MDFI_API_URL": "https://api.mdfi.ai"
      }
    }
  }
}

The connector is the mdfi-connect package. Its source is public on GitHub under the Apache-2.0 licence; it holds no conversion code and only calls the mdfi API. Claude Code users can also install it as a plugin, which asks for the key when it is installed: /plugin marketplace add TopTop-Oy/mdfi-connect, then /plugin install mdfi@mdfi.

The connector gives the agent three tools: read_document, read_pages and export_table. The Connector page describes each one.

Read a first document

Ask your agent:

Read docs/report.pdf with mdfi and summarise the tables.

The agent calls read_document("docs/report.pdf"). The connector computes the file's SHA-256 and asks mdfi whether your account already has that file. If it does not, the connector uploads it. It then waits up to 20 seconds for the outline or the first pages and returns what is there.

What your agent sees

For a finished 12-page report, read_document returns something like this (the page text is shortened here):

mdfi document: report.pdf
document_id: 1b4e28ba-2fa1-41d2-883f-0016d3cca427
pages: 12 (ready 12 of 12)
status: ready
quality: average page score 96/100 over 12 scored page(s); 1 page(s) need care
charged: 20 weighted pages (once; re-reads are free)
shown below: pages 1–2 of 12 (use read_pages for the rest)
⚠ uncertain — verify before relying on these:
  - table p5-t1 on p5-6: "Total" row 14 does not add up in column "2025"
  - read by OCR on page(s) 9
  - OCR noise on page(s) 9
  - low quality on page(s) 9
read from scans: pages 11
table notes: p5-t1 (continues on page 6); p7-t1 (read by vision — verify)
outline:
- Summary (p1-3)
- Results (p3-10) ⚠
  - Regional results (p5-10) ⚠
- Appendix (p10-12)

--- page 1 ---
## Summary
Revenue grew in every region except the north. …

--- page 2 ---
…

[Shown: pages 1–2 of 12. Use read_pages with pages="…" or section="<heading>" for the rest.]

What this tells the agent:

  • The outline comes first. A document of up to about 10,000 tokens comes back whole. A longer one comes back as its outline and its first pages (about 3,000 tokens), and the agent asks for the rest with read_pages, by page number ("3,7,9-11") or by a heading from the outline (section="Regional results").
  • Anything uncertain is marked with ⚠. Here, one table's total does not add up and page 9 is a poor scan, so the outline entries that contain them carry a ⚠ too. Page 11 is a scan that was read cleanly, so it is listed without a warning. How it works explains every flag.
  • The charge is shown once. This report cost 20 weighted pages: 10 pages read at Tier 1 (1 each) and two pages that went on to a vision model (5 each). Pricing has more examples.

A large document may still be converting when read_document returns. The header then says status: converting and charged: nothing yet — charged once when conversion completes, and the last line starts with STILL CONVERTING — this is partial. It names the pages that are ready and, when it has one, an estimate of the time left. PDF pages become readable a few at a time while the rest converts; How it works says when each format's pages become readable. The agent reads what is ready and calls read_document again with the same path later: no new upload, no extra charge.

Re-reads are free

A document is charged once, when its conversion completes. Calling read_document again on the same file sends only its SHA-256, so nothing is uploaded or charged again; read_pages and export_table never charge. Your account keeps a converted document for 7 days; after that, reading the file converts and charges it again.

Next

  • How it works: tiers, page scores, flags, escalation, outline and tables.
  • Pricing: plans, weighted pages, what counts as a page, limits.
  • Connector: the three tools and every error message.
  • API: the HTTP API behind the connector.
  • Data and privacy: what is kept, for how long, and what leaves mdfi.