# HTML to PDF in Codex

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):

```bash
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:

```bash
export HTML_PDF_KEY=hp_live_...
```

## Connect

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

```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:

```bash
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](https://html-pdf.com/docs).

Full reference: [API docs](https://html-pdf.com/docs) · [MCP server](https://html-pdf.com/mcp)