# PDFen

> PDFen is a document processing service for converting, merging, compressing, and OCR-ing PDF files and other document formats. It offers two integration paths: a REST API and an MCP server (for use with Claude and other AI assistants).

## REST API

Authentication: Bearer token. Generate one at https://pdfen.com/profile/api-tokens

Base URL: `https://pdfen.com/api/v2`

OpenAPI spec: https://pdfen.com/api/docs/v2/spec

Key endpoints:
- `POST /api/v2/convert` — convert files (upload + workflow execution)
- `GET /api/v2/executions/{id}` — check conversion status
- `GET /api/v2/executions/{id}/download` — download converted file
- `GET /api/v2/user/workflows` — list available workflows
- `GET /api/v2/workflows/{id}/options` — get configurable options for a workflow
- `GET /api/v2/user/credits` — check credit balance
- `GET /api/v2/user` — get user info

Credits: each conversion costs credits (1 credit per document by default). Organization credits are used before personal credits.

Guides: https://pdfen.com/api/docs/guides/getting-started

## MCP Server

PDFen has an MCP server that lets Claude convert files to PDF directly, without switching to the web app.

**SSE endpoint:** `https://pdfen.com/mcp/sse`
**Auth:** `Authorization: Bearer YOUR_API_TOKEN`
**Full setup guide:** https://pdfen.com/api/docs/guides/mcp

### Connecting (Claude Desktop)

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pdfen": {
      "url": "https://pdfen.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}
```

### Available tools

| Tool | Description |
|------|-------------|
| `get_user` | Account info and license tier |
| `get_credits` | Credit balance, including organization pools |
| `list_workflows` | All available conversion workflows (system + personal + org) |
| `get_workflow_options` | Configurable options for a workflow (OCR, PDF/A, compression, etc.) |
| `start_conversion` | Start a conversion — returns `execution_id` immediately |
| `get_execution_status` | Poll status: `pending`, `processing`, `done`, or `error` |
| `get_download_url` | Get a signed download URL (valid 1 hour) — only when status is `done` |
| `get_upload_capabilities` | Check available file input modes and size limits |

### Typical conversion flow

```
1. list_workflows           → find the right workflow_id
2. start_conversion         → submit files, receive execution_id + credits_charged
3. get_execution_status     → poll until status is "done"
4. get_download_url         → get signed URL, valid for 1 hour
```

### File input modes

| Mode | Max size | Notes |
|------|----------|-------|
| `file_url` | Up to license limit | Public HTTPS URL; fetched server-side |
| `file_base64` | 5 MB | Inline base64-encoded file |
| `file_path` | Up to license limit | Local path — stdio variant only |

### Error codes

| Code | Meaning |
|------|---------|
| `insufficient_credits` | Top up at pdfen.com/credits |
| `file_too_large_for_base64` | Use `file_url` instead |
| `file_path_not_available_on_remote` | `file_path` requires the stdio variant |
| `workflow_not_found` | Use `list_workflows` to find valid IDs |
| `not_completed` | Poll with `get_execution_status` first |
| `rate_limit_exceeded` | Limit: 100 requests/minute |