HTML to PDF in Codex

Q: How do I add an MCP server to Codex CLI?

Add an [mcpservers.html-pdf] table to ~/.codex/config.toml with the url and bearertokenenvvar, or run codex mcp add. Then run /mcp to check the tools.

Q: Where should I keep my API key?

Keep it in the HTMLPDFKEY environment variable. Codex reads it from there, so the key never sits in config.toml.

Q: Can I use it in CI without Codex?

Yes. Call POST https://html-pdf.com/v1/pdf directly with Authorization: Bearer $HTMLPDFKEY and a JSON body with html or url. See the API docs. Full reference: API docs · MCP server

Add HTML and URL to PDF conversion to OpenAI Codex CLI with the html-pdf.com remote MCP server. It takes three lines of config.toml and no local install.

Quick answer: run codex mcp add html-pdf --url https://html-pdf.com/mcp --bearer-token-env HTML_PDF_KEY with your key in HTML_PDF_KEY, then ask Codex "Make a PDF of https://example.com".

Get an API key

You need a key before you connect. Create one with a single call (or by email at https://html-pdf.com/login):

curl -X POST https://html-pdf.com/v1/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

The key is shown once. Open the link we email you to confirm your address, which adds 100 free credits (1 credit = 1 PDF page). Then export the key in your shell profile:

export HTML_PDF_KEY=hp_live_...

Connect

This step registers the server with Codex. Add it to ~/.codex/config.toml:

[mcp_servers.html-pdf]
url = "https://html-pdf.com/mcp"
bearer_token_env_var = "HTML_PDF_KEY"

Codex reads the key from HTML_PDF_KEY and sends it as Authorization: Bearer .... The key never sits in the config file.

Or add it from the CLI:

codex mcp add html-pdf --url https://html-pdf.com/mcp --bearer-token-env HTML_PDF_KEY

Start Codex and run /mcp to see the html-pdf tools.

Try it

Once connected, you just ask in plain words. You don't write any code. For example:

"Render report.html to a Letter PDF with 20mm margins and save the download link to REPORT_URL.txt."
"Make a PDF of https://example.com and tell me how many pages it has."
"Build an HTML invoice from order.json and convert it to PDF with html-pdf."

Tips

These options help you get cleaner PDFs and safer automation.

Page breaks: break-before: page between sections and break-inside: avoid on blocks that must stay together.
Page numbers: footer_html with <span class="pageNumber"></span> and <span class="totalPages"></span>. Set a bottom margin.
Set max_pages in prompts for generated documents. Renders over the limit fail and cost nothing.
Scripts: for CI or cron jobs, have Codex write a script that calls POST https://html-pdf.com/v1/pdf with "response": "url" to get a JSON response with a 24h link.

Troubleshooting

Most issues come from a missing environment variable or a typo in the TOML.

Server fails to start or returns 401: HTML_PDF_KEY isn't set in the environment Codex was started from. Run echo $HTML_PDF_KEY and restart Codex.
TOML parse error: the table name must be exactly [mcp_servers.html-pdf], and values need double quotes.
403 email_not_confirmed: the email behind the key isn't confirmed yet. Click the link we emailed you (it adds the 100 free credits), then try again.
402 insufficient_credits: ask Codex to call buy_credits for a Stripe link. Purchased credits never expire.

FAQ

How do I add an MCP server to Codex CLI?

Add an [mcp_servers.html-pdf] table to ~/.codex/config.toml with the url and bearer_token_env_var, or run codex mcp add. Then run /mcp to check the tools.

Where should I keep my API key?

Keep it in the HTML_PDF_KEY environment variable. Codex reads it from there, so the key never sits in config.toml.

Is there a free tier?

Yes. A new account gets 100 free credits once you confirm your email, with no card. 1 credit = 1 PDF page, and failed renders cost nothing.

Can I use it in CI without Codex?

Yes. Call POST https://html-pdf.com/v1/pdf directly with Authorization: Bearer $HTML_PDF_KEY and a JSON body with html or url. See the API docs.

Full reference: API docs · MCP server