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](https://app.mdfi.ai/signup), confirm your email address, then press **Choose Starter** or **Choose Pro** on the Billing page and pay through Stripe Checkout. [Pricing](pricing.md) 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](https://docs.astral.sh/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. ```bash 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. ```json { "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`](https://pypi.org/project/mdfi-connect/) package. Its source is public on [GitHub](https://github.com/TopTop-Oy/mdfi-connect) 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](connector.md) 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): ```text 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="" 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](how-it-works.md#flags-and-warnings) 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](pricing.md#worked-examples) 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](how-it-works.md#outline-first-then-pages) 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](how-it-works.md): tiers, page scores, flags, escalation, outline and tables. - [Pricing](pricing.md): plans, weighted pages, what counts as a page, limits. - [Connector](connector.md): the three tools and every error message. - [API](api.md): the HTTP API behind the connector. - [Data and privacy](data.md): what is kept, for how long, and what leaves mdfi.