MCP server

Connect your AI client to pdf-mcp, sign in with OAuth, and create, read, or edit PDFs.

On this page

Connect your AI client to pdf-mcp to create PDFs, extract text, fill forms, and work with stored documents. The server is hosted: add the URL, sign in, and enable its tools.

Connect a client

Add to Cursor Add to VS Code

These links open the installed client with the server configuration ready to review. Complete the browser sign-in to authorize access. They contain no API key. If your browser does not launch the app, use the manual setup in its guide.

Client	Setup
Claude	Add a remote connector and sign in
ChatGPT	Create a connection in developer mode
Cursor	One-click installation or JSON configuration
VS Code	One-click installation or MCP: Add Server
Claude Code	Add the server in your terminal, then authenticate
Codex	Add the server and run the OAuth login command

Server URL

All clients use the same endpoint:

Plain text

https://api.pdf-mcp.io/mcp

Setting	Value
Transport	Streamable HTTP
Authentication	OAuth with browser sign-in
Client registration	Automatic through Dynamic Client Registration (DCR)
Local package	None required

For another client, choose its HTTP or Remote MCP connection type and paste this URL.

How authentication works

Your client discovers the authorization server, registers itself, and opens the pdf-mcp sign-in page. Sign in, select your workspace, and approve the requested access. The client stores and refreshes its OAuth tokens.

The connection stays bound to that workspace. Switching workspaces in the dashboard does not change it. Calls use that workspace’s credits and your current permissions. See Workspaces for roles and resource access.

Most clients do not need a manually created OAuth app. If a client requires fixed credentials, follow manual OAuth registration.

API-key fallback

Clients that support custom HTTP headers can use a pdf-mcp API key instead:

Plain text

Authorization: Bearer pdfmcp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Store the key in the client’s secret store or an environment variable. Keep it out of shared project configuration. Codex includes an environment-variable example. ChatGPT uses OAuth.

Available tools

Your client discovers the full tool schemas when it connects. Its live tool list is the reference for names and parameters.

Task	Tools
Create PDFs	`html_to_pdf`, `text_to_pdf`, `image_to_pdf`
Read and inspect	`extract_text`, `grep_pdf`, `pdf_to_image`, `get_page_count`
Edit PDFs and forms	`extract_pages`, `merge_pdfs`, `get_form_fields`, `fill_form`, `crop_pdf`
Manage documents	`upload_pdf`, `list_documents`, `get_document`, `download_document`, `search_documents`, `delete_document`
Work with templates	`create_template`, `update_template`, `list_templates`, `get_template`, `render_template`, `generate_template`
Publish templates	`publish_template`, `rollback_template`, `list_template_versions`
Manage assets	`upload_asset`, `list_assets`, `delete_asset`
Work with themes	`create_theme`, `list_themes`, `publish_theme`, `rollback_theme`, `list_theme_versions`

Consumers can use PDF tools and published templates visible to them. Authoring templates, themes, assets, and drafts requires editor or admin access. Private templates remain visible only to their creator. Consumers and editors see their own files; admins can access all files in the bound workspace.

The server also provides the MCP resources docs://skill-guide and docs://print-guide for clients that support resources.

File delivery and storage

By default, PDF-producing tools use your workspace’s configured storage mode. Managed storage (default) and your own bucket (byob) keep documents private and return a document ID and a signed browser view link.

Use storage_mode: "memory" to return PDF bytes as an embedded resource without storing a document. To store a PDF and also return its bytes, set return_binary: true.

JSON

{
  "html": "<h1>Hello, PDF!</h1>",
  "storage_mode": "default",
  "return_binary": true
}

Whether embedded bytes appear as a file attachment depends on your client. The returned browser view link opens the stored PDF without an authorization header. See Storage modes for response details.

Example prompts

Use pdf-mcp to create an A4 invoice from these line items. Store it and return the browser view link.

Use get_form_fields on this stored PDF, then fill the form with the values I provide and return a flattened PDF.

Search my stored documents for “Acme”, merge the matching invoices in date order, and keep the merged PDF in managed storage.

Troubleshooting

Problem	What to do
Client asks for a command	Select an HTTP or remote server and enter the URL directly
`401 Unauthorized` before sign-in	Use the client’s Connect, Authenticate, or Sign in action; the initial challenge starts OAuth discovery
Browser authorization does not start	Check the endpoint, clear the server’s saved authentication, and reconnect
Client requires a fixed ID or callback	Register an OAuth app using the exact callback URI it displays
`402 Payment Required`	Ask a workspace admin to add credits, or check your member credit limit
`403 Forbidden`	Check that credentials are active and your membership, role, and scopes allow the action
PDF is not attached	Use its browser view link, call `download_document`, or request `return_binary: true`

For authentication discovery and scope details, see Authentication.