Skip to main content
Install Codex CLI using the npm tab in the installation instructions, then complete the PDF.co MCP prerequisites. These instructions use native Windows PowerShell, the npm-installed Codex CLI, and a local Codex session. The codex.cmd commands use npm’s Windows launcher. If you already added pdfco through the desktop app’s Add MCP server form on the same host, skip configuration and continue with Open a new session.

​
Add the server from PowerShell

Find your uvx.exe path:
Replace the executable path below with that output. Replace only YOUR_PDFCO_API_KEY with your PDF.co API key, keeping the X_API_KEY= prefix:
The --env argument must be in KEY=VALUE form. The server reads the key from the environment variable named X_API_KEY.
PowerShell command adding the pdfco MCP server with X_API_KEY and an absolute path to uvx.exe

Example registration command in Windows PowerShell, with an API-key placeholder.

The command saves the server in %USERPROFILE%\.codex\config.toml, or in CODEX_HOME if you set a custom location. The desktop app and CLI share settings on the same Codex host; configure pdfco only once.

​
Open a new session

Check that pdfco is listed as enabled, then start Codex:
In the new Codex session, enter /mcp to inspect the active servers and PDF.co tools. codex.cmd mcp list confirms configuration; the active connection and a real tool call confirm that the server works.

​
Run a sample conversion

Codex CLI showing one prompt requesting PDF.co conversion and job completion

The sample conversion prompt in Codex CLI 0.162.1 on Windows.

Approve the tool calls when requested, inspect the final job result, and open the text file. See Verify your connection.
Codex CLI calling pdf_to_text followed by wait_job_completion and showing a successful one-page conversion with the signed URL credentials redacted

A completed PDF-to-text conversion, with signed output URL details hidden.

Close and reopen Codex CLI, then repeat the prompt to check that the saved configuration still works.

​
Troubleshooting

  • If mcp add reports that environment entries must be in KEY=VALUE form, keep X_API_KEY= before your key inside the quoted --env argument. A key by itself is not a valid argument.
  • If the configuration cannot be parsed, check that mcp_servers.pdfco and its env table each appear only once.
  • If the server cannot start, check the absolute path to uvx.exe and inspect the startup error shown by Codex.
  • If settings differ between projects, check for project-level .codex/config.toml overrides.
  • If tools load but processing fails, inspect the PDF.co error response and check the API key.
See OpenAI’s MCP documentation for configuration options.