# MCP server

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](cursor://anysphere.cursor-deeplink/mcp/install?name=pdf-mcp&config=eyJ1cmwiOiJodHRwczovL2FwaS5wZGYtbWNwLmlvL21jcCJ9)
[Add to VS Code](vscode:mcp/install?%7B%22name%22%3A%22pdf-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapi.pdf-mcp.io%2Fmcp%22%7D)

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](https://pdf-mcp.io/docs/mcp-client-claude) | Add a remote connector and sign in |
| [ChatGPT](https://pdf-mcp.io/docs/mcp-client-chatgpt) | Create a connection in developer mode |
| [Cursor](https://pdf-mcp.io/docs/mcp-client-cursor) | One-click installation or JSON configuration |
| [VS Code](https://pdf-mcp.io/docs/mcp-client-vscode) | One-click installation or MCP: Add Server |
| [Claude Code](https://pdf-mcp.io/docs/mcp-client-claude-code) | Add the server in your terminal, then authenticate |
| [Codex](https://pdf-mcp.io/docs/mcp-client-codex) | Add the server and run the OAuth login command |

## Server URL

All clients use the same endpoint:

```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](https://pdf-mcp.io/docs/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](https://pdf-mcp.io/docs/authentication#when-to-create-an-oauth-app).

### API-key fallback

Clients that support custom HTTP headers can use a [pdf-mcp API key](https://pdf-mcp.io/docs/authentication#api-keys) instead:

```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](https://pdf-mcp.io/docs/mcp-client-codex#api-key-alternative) 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](https://pdf-mcp.io/docs/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](https://pdf-mcp.io/docs/authentication#when-to-create-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](https://pdf-mcp.io/docs/authentication).