The PDF API includes a built-in MCP (Model Context Protocol) Server that enables AI agents like Claude to generate, manipulate, and analyze PDF documents directly. This provides a standardized interface for AI-powered PDF workflows.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to interact with external tools and services. By exposing the PDF API as an MCP server, AI agents can:

• Generate PDFs from HTML, text, or images
• Extract text and data from existing PDFs
• Merge, split, and manipulate PDF documents
• Store, search, and manage generated documents
• All within natural language conversations

Available Tools

The MCP server exposes 14 tools organized into three categories:

PDF Generation & Manipulation

PDF Analysis

File Management

Storage & File Delivery

Why MCP defaults to cloud storage

By default, MCP tools store generated PDFs in the pdf-mcp cloud bucket (default mode) rather than returning raw bytes. This is intentional and optimized for AI agent workflows:

• Token efficiency. A 100 KB PDF base64-encoded is ~133 KB of text — roughly 32,000 tokens. With cloud storage, the LLM only sees a short metadata summary (~100 tokens).
• File management. Stored documents get a document_id for retrieval, search, and organization across conversations.
• Multi-step workflows. Reference previously generated PDFs by URL or ID for merge, split, or convert operations.
• Universal compatibility. Presigned URLs and the download endpoint work from any environment.

You can override this by passing storage_mode: "memory" to any generation tool. See Storage Modes for full details.

How responses work

MCP tools return structured content that separates what the LLM sees from the actual file data:

Stored mode (default):

1. TextContent — Metadata summary with document ID, size, page count, presigned URL, and download instructions
2. EmbeddedResource — The PDF binary as a blob, so smart MCP clients (like Claude Desktop) can save the file to disk automatically

Memory mode:

1. TextContent — Short summary (e.g., “PDF generated: report.pdf (45 KB)”)
2. EmbeddedResource — The PDF binary blob for client-side saving

In both cases, the LLM sees only the small text summary. The binary data flows through EmbeddedResource to the MCP client without consuming context window tokens.

Setup with Claude Desktop

To use the PDF MCP server with Claude Desktop, add it to your MCP configuration:

1. Locate Your Config File

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

2. Add the PDF MCP Server

Edit the configuration file to include the PDF MCP server:

{
  "mcpServers": {
    "pdf-mcp": {
      "url": "https://api.pdf-mcp.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with your actual API key from the dashboard.

3. Restart Claude Desktop

After saving the configuration, restart Claude Desktop for the changes to take effect.

Tool Reference

html_to_pdf

Convert HTML content to a PDF document.

Parameters:

Example prompt:

“Generate a PDF invoice with the company name ‘Acme Corp’, invoice number #12345, and a line item for ‘API Access’ at $49.00”

text_to_pdf

Convert plain text to a formatted PDF document.

Parameters:

Example prompt:

“Convert this meeting notes text to a PDF document”

image_to_pdf

Convert images to a PDF document with each image on a separate page.

Parameters:

Example prompt:

“Combine these three images into a single PDF document”

pdf_to_image

Convert PDF pages to images (PNG or JPEG format).

Parameters:

Note: Provide either pdf_base64 or pdf_url, not both.

Example prompt:

“Convert the first page of this PDF to a high-resolution PNG image”

extract_text

Extract text content from a PDF document.

Parameters:

Example prompt:

“Extract all the text from this PDF and summarize the main points”

grep_pdf

Search PDF content using pattern matching.

Parameters:

Example prompt:

“Search this PDF for any email addresses”

extract_pages

Extract or rearrange specific pages from a PDF.

Parameters:

Example prompt:

“Extract pages 1, 3, and 5 from this PDF into a new document”

merge_pdfs

Combine multiple PDF documents into one.

Parameters:

Note: Provide at least one of pdfs_base64 or pdfs_url. Both can be combined.

Example prompt:

“Merge these three PDF documents into a single file”

get_page_count

Get the total number of pages in a PDF.

Parameters:

Example prompt:

“How many pages are in this PDF document?“

list_documents

List all stored documents with pagination.

Parameters:

Example prompt:

“Show me my recent PDF documents”

get_document

Retrieve a single document’s metadata and a fresh presigned download URL.

Parameters:

Example prompt:

“Get the download link for document abc-123”

download_document

Download a stored PDF document. Returns the PDF as an EmbeddedResource that the MCP client can save to disk.

Parameters:

Example prompt:

“Download the invoice PDF I generated earlier”

delete_document

Delete a document from storage.

Parameters:

Example prompt:

“Delete the test PDF I generated”

search_documents

Search stored document contents using full-text search or substring matching.

Parameters:

Example prompt:

“Find all invoices that mention ‘Acme Corporation‘“

Example Workflows

Generate and Store

User: "Create a quarterly report PDF with these financial figures"

Agent:
1. html_to_pdf(html="...", filename="q4-report.pdf")
   → PDF stored, document_id: abc-123

The PDF is automatically stored. The agent sees the document ID and metadata. The MCP client receives the PDF blob via EmbeddedResource for local saving.

Multi-Step Pipeline

User: "Take this 10-page PDF, extract just pages 2-4, then convert them to images"

Agent:
1. extract_pages(pages=[2,3,4], pdf_url="https://...")
   → New PDF stored, document_id: def-456
2. pdf_to_image(pdf_url="[presigned URL from step 1]")
   → Returns page images

Search and Retrieve

User: "Find the invoice for Acme Corp and download it"

Agent:
1. search_documents(query="Acme Corp")
   → Found document_id: ghi-789
2. download_document(document_id="ghi-789")
   → PDF returned as EmbeddedResource

Memory Mode (No Storage)

User: "Generate a quick PDF preview, don't store it"

Agent:
1. html_to_pdf(html="...", storage_mode="memory")
   → PDF returned directly, nothing stored

Error Handling

The MCP server returns structured errors that AI agents can interpret:

AI agents will typically explain these errors in natural language and suggest corrections.

Self-Hosted MCP Server

For maximum control and performance, you can self-host the PDF MCP server:

Python Integration

from mcp_server import create_mcp_server
from fastapi import FastAPI

app = FastAPI()

# Create and mount MCP server
mcp = create_mcp_server("My PDF MCP")
app.mount("/mcp", mcp.streamable_http_app())

Requirements

mcp[cli]>=1.0.0
weasyprint>=60.0
pypdf>=4.0.0
pdf2image>=1.16.0
Pillow>=10.0.0
httpx>=0.25.0

Best Practices

For AI Agent Prompts

• Be specific about document structure: “Create an invoice with header, line items table, and footer”
• Specify output preferences: “Generate a PDF in A4 size with 2cm margins”
• Describe styling needs: “Use a professional, minimal design with blue accents”

For Integration

• Store API keys securely (never expose in client-side code)
• Implement proper error handling in your MCP client
• Use default storage mode (the default) for document management workflows
• Use memory mode only when you need disposable, one-off PDFs
• Monitor usage through the dashboard

Performance Tips

• Use URL-based input (pdf_url) for large files already hosted online
• Extract only needed pages to reduce processing time
• For batch operations, consider parallel tool calls
• Let the default storage mode handle file delivery — avoid passing large base64 blobs between tools when you can use document IDs or URLs instead

Related Documentation

• Storage Modes - Deep dive into storage behavior and channel defaults
• Quick Start - Get your API key and make your first request
• Files API - REST API for file management
• HTML to PDF - Detailed REST API documentation
• Authentication - API key and OAuth setup

Credit Usage

MCP tools use the same credit system as the REST API:

• Generation tools (html_to_pdf, text_to_pdf, image_to_pdf): ~1 credit per page generated
• Manipulation tools (extract_pages, merge_pdfs): ~0.01 credits per request
• Extraction tools (extract_text, grep_pdf, pdf_to_image): ~0.01 credits per page processed
• Utility (get_page_count): ~0.01 credits per request
• Search (search_documents): ~0.01 credits per search
• File management (list_documents, get_document, download_document, delete_document): Free