Codex + pdfmcp: setup guide

Add pdfmcp to OpenAI Codex via config.toml.

What you need: a free pdfmcp API key — sign in with your email (no password) and copy the key shown at first login. Then replace pdfmcp_live_YOUR_KEY in the config below.

Where it goes: ~/.codex/config.toml

[mcp_servers.pdfmcp]
url = "https://mcp.pdfmcp.org/mcp"
http_headers = { "X-API-Key" = "pdfmcp_live_YOUR_KEY" }

Steps

Get a free API key from the pdfmcp dashboard and replace pdfmcp_live_YOUR_KEY in the config.
Append the block above to ~/.codex/config.toml.
Restart Codex and ask it to list available MCP tools — pdfmcp's operations will be there.
Try: “Use pdfmcp to add page numbers to this PDF”.

Troubleshooting

401 / unauthorized: the key header is missing or mistyped. The header name is exactly X-API-Key (Claude Code uses Authorization: Bearer … — both work).
Tools don't appear: fully restart the client after editing its config; most clients only load MCP servers at startup.
Server unreachable: check the public status page — and your network's outbound HTTPS to mcp.pdfmcp.org.

Try it with

On-deviceCompress PDFReduce file size with Ghostscript. Presets: light (printer quality), medium (ebook), heavy (screen, smallest).API · MCPOCR — searchable PDFMake a scanned PDF searchable: pages without a text layer are OCR'd with Tesseract and gain an invisible text layer; pages that already have text are passed through and reported as skipped.API · MCPPDF to Word (DOCX)Convert a PDF to an editable Word document. Text-based conversion: paragraphs and headings are reconstructed from the text layer; exact layout, tables and images are not preserved.

More clients: Claude Desktop MCP setup · Claude Code MCP setup · ChatGPT MCP setup · All MCP setup guides · REST API quickstart