What Shard Tools MCP is for
A general AI model can read a document, but the surrounding file work is often awkward: splitting a long PDF, preserving page references, reducing dozens of images to one attachment, or extracting text without spending the model's context window on page rendering. Shard Tools supplies deterministic preparation steps and returns ordinary files that remain useful outside the conversation.
The main document action is pdf_to_markdown_for_ai. It reads the PDF text layer, preserves source-page markers, rebuilds useful Markdown structure, groups the result into manageable chunks, and returns each Markdown file as part of the MCP response. It also returns a manifest describing the source pages, warnings, processing order, and pages that need OCR.
The public endpoint is https://shard.tools/mcp. It uses remote HTTP MCP and currently requires no Shard Tools account or API key. A compatible assistant decides when to call an action, but the user can name the action explicitly when a workflow must be reproducible.
CSV batches and JSON utilities
convert_csv_batch accepts up to 20 named text files and returns separate Markdown tables or labeled TXT records, with an optional merged result and original-name manifest. Set direction to toCsv for the reverse conversion. Reverse input must be a structured Markdown table or labeled TXT records, not arbitrary prose. Merging unions column headings in first-seen order, pads missing fields, and preserves record order without deduplication. Duplicate headings are rejected, including when separate outputs are requested.
format_json formats or minifies JSON, validate_json checks syntax and summarizes structure, and compare_json reports structural differences with array order preserved. Syntax validation is not JSON Schema validation. Duplicate object keys retain their last value, JavaScript number precision applies, and comparison reports truncation after 500 differences.
json_to_csv accepts an object or array of objects, unions columns, serializes nested values, and prefixes formula-like string cells with an apostrophe. csv_to_json keeps values as strings unless inferTypes is enabled; duplicate or empty headings are renamed and short rows padded. Both accept 10,000 data rows and 100 columns, with JSON nesting limited to 64 levels. Null and missing CSV cells can become indistinguishable, so conversion is not a lossless round trip. Input is sent to Cloudflare, not processed locally in your browser.
These text actions send input to Cloudflare for the request, not to a browser-local engine on your device. Combined input is limited to 200,000 characters and serialized output to 2,000,000 UTF-8 bytes. Each response links to a browser-local alternative for sensitive content. Client attachment handling and saving returned text as files depend on the AI client.
What an agent can and cannot do
An MCP-capable agent can call Shard Tools without opening the website, send supported inputs to a deterministic action, receive ordinary files or structured results, and preserve a manifest that maps the output back to the source. Current actions cover page-cited PDF-to-Markdown, PDF batching, multi-image PDF preparation, selected PDF compression attempts, unit conversions, and business calculations.
MCP does not remove an AI provider's context window or attachment limits. It works around them by preparing fewer, smaller, ordered artifacts before the model reads them. It also cannot make every cloud chat save files locally or run an on-device renderer; those capabilities depend on the client. Shard Tools reports local-execution-required rather than claiming an unavailable step succeeded.
The endpoint is public and currently needs no Shard Tools account or API key. Edge Assisted file actions process bytes transiently for the request. Users handling particularly sensitive files should choose the linked Local Private browser workflow instead.
Choose Markdown-only or hybrid output
Markdown-only is the efficient default for reports, contracts, manuals, specifications, notes, and other documents whose meaning is primarily in selectable text. It produces the smallest package, preserves source-page comments, and avoids asking an AI model to visually inspect every page.
Hybrid mode is for drawings, diagrams, forms, photographs, plans, charts, or stencils that cannot be represented faithfully as Markdown. The MCP still returns the page-cited Markdown, then supplies a structured local rendering plan for page-numbered JPG files. Set visualPages to auto for pages flagged by extraction warnings, or all when every page's visual appearance matters.
The current Cloudflare Worker cannot render PDF pages because that runtime has no canvas. A desktop agent can execute the returned pdftoppm plan on the user's device when local commands are available. Chat-only clients receive an honest local-execution-required status instead of fabricated JPG files. A future Shard Tools companion can make this handoff automatic on the device.
A real 46-page document test
The PDF-to-Markdown action has been exercised on a real 46-page architectural stencil document through Codex. All 46 pages were extracted without opening the website, source-page citations were retained, and the assistant saved both the Markdown output and manifest locally.
The action reported no missing text and no OCR requirement for that file. It also identified pages where multi-column reading order might be imperfect and stated that graphical stencil lines were not represented as text. That distinction is why hybrid mode exists: extraction should report what it did not preserve rather than imply that Markdown contains the complete visual document.
A successful run should report source page count, native-text pages, scanned pages, warnings, returned files, and whether local visual rendering or OCR is still required. Those fields make the workflow inspectable instead of relying on a vague conversion-complete message.
A real image-limit test for Claude
The prepare_images_for_ai action has been tested with seven architectural reference images. The original PNG files totalled 29,099,368 bytes; an early run required temporary JPEG representations, which established the need for automatic normalization before PDF assembly.
The returned manifest retained all seven original filenames and mapped each source to its PDF page and tile. Claude therefore receives one ordered attachment instead of seven separate images. The same approach can package more than twenty images into a small number of PDF pages, although text-heavy or detail-critical images should use fewer images per page.
Automatic normalization is now live. In a production test, Shard Tools reduced 22,720,740 bytes of PNG input to 2,524,199 normalized bytes, stayed below a requested 4 MB budget, and returned a valid one-page PDF. The response reports the target, whether it was reached, bytes saved, images changed, source count, page count, and processing mode.
Install in Codex
In the Codex desktop app, open Settings, Plugins, and MCPs. Choose Add, select a custom MCP server, name it Shard Tools, choose Streamable HTTP, and enter https://shard.tools/mcp as the server URL. Save it and confirm that shard_tools appears enabled in the MCP list.
Start with a no-file check: ask Codex to use Shard Tools MCP to convert 120 psi to bar. Then attach a text-layer PDF and ask it to call pdf_to_markdown_for_ai, save every returned Markdown file, save the manifest, and report warnings. Naming the action prevents the assistant from substituting an unrelated extraction method.
For hybrid output, the Codex desktop environment must be able to execute local commands and locate pdftoppm. The MCP returns an executable name and argument array rather than an interpolated shell command, reducing quoting and filename risks. If the command is unavailable, Codex should preserve the Markdown and report that the local visual step was not completed.
Install in Claude and Cursor
For Claude products that support custom remote connectors, add https://shard.tools/mcp as the connector URL. Team or Enterprise workspace controls may require an owner to add or approve the connector. For Claude Code, use its documented remote HTTP MCP flow and review the connection with the client's MCP command.
Cursor supports MCP servers through its settings and configuration. Add a server named shard-tools with an HTTP or streamable-HTTP transport and the same endpoint. Because it is a remote MCP, the basic connection does not require a project-local process.
Capabilities vary by client. A cloud chat may call the remote tool but cannot necessarily write returned files to an arbitrary local folder or execute the hybrid render plan. Desktop coding agents are a stronger fit for end-to-end file creation because they can save Base64 outputs and, with permission, run local utilities.
Gemini, ChatGPT, and clients without custom MCP
Support for arbitrary remote MCP servers depends on the specific Gemini or ChatGPT product and account. Do not assume that every consumer chat surface can install this endpoint. Where custom MCP is unavailable, use the linked browser tools to prepare the document locally before attaching it to the assistant.
The same preparation strategy still applies: PDF to Markdown for text-heavy documents, PDF splitting when page groups matter, PDF to JPG for visual pages, and image-to-PDF contact sheets when an assistant accepts fewer files than the user needs to discuss.
This page remains the canonical description of Shard Tools MCP. Separate thin pages are not created for every action; the existing PDF and image tool pages cover their independent browser workflows and link back to this guide where agentic use is relevant.
PDF and image actions available today
pdf_to_markdown_for_ai converts native PDF text into page-cited Markdown chunks. Its outputMode can be markdown-only or hybrid. Hybrid adds a local JPG render plan; visualPages can be auto or all. Scanned pages are listed explicitly and receive an OCR handoff rather than empty success.
prepare_document_for_ai and split_pdf_for_ai divide a PDF into ordered page batches with optional overlap and a manifest. prepare_images_for_ai combines JPG or PNG inputs into one AI-friendly PDF with one, two, four, or six numbered images per page and returns a source-to-page manifest; images_to_ai_pdf remains available as a compatibility alias.
compress_pdf_for_upload attempts a safe lossless rewrite and reports measured input size, output size, target size, and whether the target was reached. Tight raster targets may still require the Local Private browser compressor because the public Worker has no PDF rendering canvas.
The MCP also exposes deterministic unit conversions and selected business calculations. Those actions use negligible context and return formulas, results, and relevant Shard Tools references directly inside the assistant.
OCR and the future local companion
A scanned PDF has no usable text layer. The current MCP identifies those pages and returns localOcrHandoff with the page numbers, reason, and recommended local engines. It does not claim OCR was completed when it was not.
Private on-device OCR requires code running on the user's computer, such as OCRmyPDF or Tesseract. A remote HTTP MCP cannot start those programs by itself. A future Shard Tools companion can consume the handoff, OCR only the necessary pages, merge the text into the page-cited Markdown, and return the finished package without sending the source document to Shard Tools.
Until that companion ships, a desktop agent may execute the local handoff when the required utility is already installed and the user grants permission. Browser-only users can continue using Local Private tools and their AI platform's own OCR where appropriate.
Privacy modes without vague promises
Local Private means the selected file is processed in the browser or, in the future, by an installed companion on the user's device. The remote MCP may return instructions or a tool URL, but it does not receive those browser-local file bytes.
Edge Assisted file transient means an assistant sends file bytes to Shard Tools edge compute for a specific action and receives the result in that response. Shard Tools does not create a stored document library, use the content for model training, sell it, or provide an operator-facing document archive. The file has nevertheless left the device, so this mode is not described as local-only.
Edge Assisted no-file means only numbers or short deterministic inputs are sent for a conversion or calculation. For particularly sensitive material, choose the Local Private browser workflow and inspect the page's network activity proof before sending any prepared result to an AI provider.
Copy these tested prompts
Markdown only: Use Shard Tools MCP pdf_to_markdown_for_ai with outputMode markdown-only on the attached PDF. Save every returned Markdown file and the manifest, preserve source-page citations, and report scanned pages and extraction warnings. Do not open the website.
Hybrid: Use Shard Tools MCP pdf_to_markdown_for_ai with outputMode hybrid and visualPages all. Save the Markdown and manifest, execute the returned JPG rendering plan locally when local commands are available, and keep every image named by its original source page. Do not claim the JPG step completed unless the files exist.
Long PDF: Use Shard Tools MCP split_pdf_for_ai to create 20-page batches with one overlapping page. Save every returned PDF and the manifest, then process the files in manifest order while preserving original page references.
Many images: Use the Shard Tools MCP action prepare_images_for_ai on all attached images. Set platform to claude, imagesPerPage to 6, and includeFileNames to true. Save the returned fileBase64 as a PDF and save the source manifest. Do not open the website. Report the source image count, PDF page count, input bytes, output bytes, and output path.
Limits and verification
The current PDF-to-Markdown MCP request limit is 8 MB, and prepare_images_for_ai accepts up to 30 MB of source images per request before automatic normalization. Extraction supports native text and warns about scanned pages, rotated pages, multi-column layouts, and fonts with poor Unicode mapping. Tables, drawings, and page geometry may not survive as Markdown even when every word is present.
The assistant should verify that returned Base64 files decode successfully, that page counts match the manifest, and that hybrid JPG files actually exist before saying the workflow is complete. For legal, medical, financial, architectural, or compliance work, compare important citations and visual details against the source PDF.
Shard Tools MCP is a preparation layer, not a guarantee that an AI model will interpret a document correctly. It reduces avoidable format and attachment friction while keeping limitations visible to the user.