Connect in one command
Claude Code speaks Streamable HTTP, so the whole setup is a single line in the terminal:
claude mcp add --transport http llmfiles https://llmfiles.com/mcp
If the configuration lives in a file instead — .mcp.json in a project, or ~/.claude.json for every project — the entry needs type. Claude Code reads an entry that has a url but no type as a stdio server and skips it, so this is the version that connects:
{
"mcpServers": {
"llmfiles": {
"type": "http",
"url": "https://llmfiles.com/mcp"
}
}
}
Claude Desktop takes a remote server as a custom connector rather than through claude_desktop_config.json: Settings → Connectors → Add custom connector, then paste the URL. There is no key field and no OAuth screen, because the server has no accounts. Cursor reads ~/.cursor/mcp.json, where a URL on its own is enough:
{
"mcpServers": {
"llmfiles": {
"url": "https://llmfiles.com/mcp"
}
}
}
VS Code keeps remote servers under servers in .vscode/mcp.json, and there type is required as well:
{
"servers": {
"llmfiles": {
"type": "http",
"url": "https://llmfiles.com/mcp"
}
}
}
In Claude Code the tools then appear as mcp__llmfiles__convert_file, mcp__llmfiles__check_pdf and mcp__llmfiles__list_formats; other clients use the names below unchanged.
The three tools
tools/list returns three tools in a 2 294-byte response, measured against the live endpoint on 10 November 2026:
| Tool | What you send | What comes back | Quota |
|---|---|---|---|
convert_file | filename and content_base64, plus optional strip_nav for HTML | the Markdown as text, and structuredContent with the file name, its size and the remaining quota | one conversion |
check_pdf | filename and content_base64 | a per-page verdict — text, scan, empty, encrypted, broken — and the command that fixes the file | free |
list_formats | nothing | 24 rows: extension groups and what each one becomes in Markdown | free |
list_formats is the call to make before asking a person for a file: it answers “do you read .msg or .ipynb?” without a wasted upload. Its answer is 2 981 bytes, and the 24 rows are groups — one covers 40+ source languages, another covers every ZIP archive, and the archive row is the one that turns twenty files into one conversion.
Why a hosted server instead of uvx
Most document MCP servers in the catalogs are installed locally — uvx mcp-pdf, npx pdftomarkdown-mcp — which means a Python or Node runtime on the machine, a package download, and a folder the server is allowed to read. A hosted server needs none of that: the client's only obligation is to POST one JSON object.
The price is base64, and it is the part that most pages about MCP converters leave out. A remote server cannot open ~/report.pdf, so the file has to travel inside the JSON: read it, encode it, send it. A 922-byte two-page PDF became 1 232 base64 characters and a 1 382-byte request body — 1.34 times the file, which is the 4/3 that base64 always costs plus the envelope around it. So the honest prompt is not “convert ~/report.pdf”; it is “read this file, encode it, call convert_file”. Claude Code does exactly that when you name a path and the tool is loaded; a hand-written request has to do it out loud:
import base64, json, urllib.request
data = base64.b64encode(open("report.pdf", "rb").read()).decode()
message = {
"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": {"name": "convert_file",
"arguments": {"filename": "report.pdf",
"content_base64": data}},
}
request = urllib.request.Request(
"https://llmfiles.com/mcp", data=json.dumps(message).encode(),
headers={"Content-Type": "application/json"})
result = json.load(urllib.request.urlopen(request))["result"]
print(result["content"][0]["text"])
print(result["structuredContent"]["quota"])
Twenty lines of standard library, no dependencies. Replace the URL with http://127.0.0.1:8090/mcp and the same script talks to a copy of the service running from the repository — that is how the measurements below were taken.
One conversion, end to end
This is the message that goes over the wire (the base64 is cut after the PDF header):
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "convert_file",
"arguments": {
"filename": "report.pdf",
"content_base64": "JVBERi0xLjQK…"
}
}
}
and this is the answer that came back, unedited:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [{"type": "text", "text": "Digital page 1 …\n\n\fDigital page 2 …"}],
"structuredContent": {
"filename": "report.pdf",
"title": "report.pdf",
"size": 922,
"fallback": false,
"quota": {"used": 3, "remaining": 22, "limit": 25}
}
}
}
structuredContent is the part a model can act on without re-reading the Markdown: size is the byte length of the file the server actually received, fallback says whether a sniffing path was used instead of the format's own converter, and quota is the counter after this call.
| File | Sent | Markdown back | Time |
|---|---|---|---|
report.pdf, 2 pages | 922 B | 79 chars, 16 words | 18 ms |
long.pdf, 60 pages | 18 482 B | 2 450 chars, 480 words | 135 ms |
handbook.docx | 1 487 B | 325 chars, 69 words | 12 ms |
page.html | 259 B | 87 chars with strip_nav, 133 without | 18 ms |
Times are loopback against the process that serves the site; over the public endpoint add the network, not the conversion. The four rows also say something about quality. The DOCX kept its heading levels — # and ## arrived exactly as written. The HTML lost the navigation and the footer: 87 characters instead of 133, with “Home”, “Pricing” and “Copyright 2026” correctly left out by the default strip_nav. The PDF came back as flat text with no headings at all, which is a property of the format and is covered in the PDF guide. And the DOCX table returned with an empty header row, because its first row held data rather than column names — the same limit the upload page has, not an MCP quirk.
When the PDF has no text layer
This is the case where an agent loop usually stalls: convert_file returns nothing readable, and the model starts guessing about OCR. check_pdf answers the question in one call and does not spend quota. Measured on a one-page scan built for this test:
scan.pdf: scan
pages: 1 (text 0, scan 1, empty 0)
page 1: scan — 1 image(s), no text
No page has a text layer: the pages are images, which is what a scanner or a
"print to PDF" from a picture produces. Run OCR first:
`ocrmypdf --redo-ocr in.pdf out.pdf` (or `--force-ocr` if the pages are photos),
then convert the OCR-ed copy — the original never needs to be uploaded anywhere.
The same file through convert_file comes back as a tool error, not as an empty document:
scan.pdf: This PDF has no text layer: its pages are images (a scan). Run OCR first
(for example, ocrmypdf --force-ocr in.pdf out.pdf, or pdftoppm plus tesseract),
then convert the OCR-ed file.
For a mixed file — text pages plus scanned pages — the same tool reports the split per page and advises ocrmypdf --skip-text instead, so OCR runs only where it is needed and the text pages are not re-OCR-ed into noise. On a three-page PDF with a real text layer it answered report.pdf: text, pages: 3 (text 3, scan 0, empty 0), 111 characters and 24 words, and the quota stayed where it was. The page-by-page logic is the one described in the PDF check article, and the same check is available without an API at all: llmfiles doctor report.pdf.
The quota, the transport, and what is not there
25 conversions a day per IP — the same counter as the upload page and POST /api/convert, so a file converted inside Claude lowers the count for the file you convert in the browser next. check_pdf and list_formats do not touch it, a failed conversion does not touch it, and a ZIP archive sent through the API costs one conversion for the whole archive. Two calls in a row returned {"used": 2, "remaining": 23, "limit": 25} and then {"used": 3, "remaining": 22, "limit": 25}. The 26th call answers with:
Daily limit reached (25 conversions per day per IP). The counter resets at midnight
UTC — a .zip of many files counts as one conversion. There is no paid plan to buy.
The transport is Streamable HTTP in its plainest form: one JSON-RPC 2.0 message per POST, no sessions and no SSE stream. GET /mcp answers 405 with Allow: POST on purpose, and a JSON-RPC batch array is refused with -32600, because batching was removed from the protocol in 2025-06-18. Compatibility follows from that sentence rather than from a logo wall: clients that POST one message and read one JSON answer work — Claude Code, Claude Desktop connectors, Cursor, VS Code, or forty lines of your own — while a client that only knows the older HTTP+SSE transport will not connect. The request body is capped at 40 MB, which is exactly where the 4/3 base64 expansion puts a 25 MB file; above that the server answers 413 before reading the body: “Request body is larger than 40 MB. The limit per file is 25 MB, and base64 adds a third.”