Create an invoice with OpenAI Codex (CLI and IDE)

Updated November 13, 2026

Codex CLI and the IDE extension can connect to the FreeInvoices remote MCP server, so Codex reads your repo's billing data and returns a link that opens a filled-in invoice. In Codex cloud, or any surface without MCP, use the import box instead.

What this setup does

Codex works inside your repository, so it can read the files that already describe your billable work: a timesheet.json, a CSV export, a list of merged pull requests, or git log. With the FreeInvoices MCP server connected, Codex turns that data into a single create_document call and gives you a link. The link opens the invoice pre-filled in your browser. You add a logo if you want one and click Download PDF.

The server is at https://freeinvoices.app/mcp. It uses Streamable HTTP, needs no account and no authentication, and offers one tool, create_document. It stores nothing and does not log the arguments.

Add the server with one command

In a terminal, register the server with codex mcp add and the --url flag, which registers a Streamable HTTP server instead of a local command. No token flag is needed because the server has no authentication.

codex mcp add freeinvoices --url https://freeinvoices.app/mcp
codex mcp list

The second command lists your configured servers so you can confirm freeinvoices is there.

Or edit config.toml

Codex stores MCP servers in ~/.codex/config.toml. The CLI and the IDE extension share that file. A project can also carry its own .codex/config.toml, but Codex only reads project-scoped config for trusted projects. Each server is a [mcp_servers.<name>] table, and an HTTP server needs only a url.

[mcp_servers.freeinvoices]
url = "https://freeinvoices.app/mcp"

~/.codex/config.toml

In the IDE extension

The extension reads the same configuration, so a server you added from the terminal is already there. You can also add one from the extension: open the gear menu, choose MCP servers, then Add server, pick Streamable HTTP, and enter the name freeinvoices and the URL above. Select Restart extension after saving. In the Codex terminal UI, type /mcp to see which servers are active.

Worked example: invoice from a timesheet

Say your repo has a timesheet.json with 22.5 hours of backend work, 6 hours of code review and QA, and a flat $250 hosting setup fee, at $95 per hour, billed to Acme Co with 8% sales tax. Ask Codex to build the invoice from it.

Codex reads the file and calls create_document with the line items. The server returns the totals it computed: subtotal $2,957.50, sales tax $236.60, total $3,194.10, balance due $3,194.10. Codex replies with the link. Open it, check the numbers, and download the PDF.

The same pattern works for a list of merged PRs. Tell Codex how to price them (a flat rate per PR, or hours from the PR descriptions) and it writes one line item per PR.

Read timesheet.json. Create an invoice for Acme Co (9 Side Rd), invoice number 2026-014, dated 2026-11-13, due 2026-11-27, in USD. Bill backend hours, review hours and the hosting fee as separate line items at $95/h, add 8% sales tax, and give me the FreeInvoices link.

Prompt to Codex in the repo

Where MCP works and where it does not

Codex CLI and the IDE extension: remote MCP over Streamable HTTP is configured as above.
Codex cloud: the Codex docs do not describe MCP server setup for cloud tasks, and cloud agent internet access is off by default. Do not count on the server there. Use the import box below.
Any other chat app, or Codex without the server: use the import box. Ask for JSON, paste the reply into the panel in the FreeInvoices editor sidebar titled Import from ChatGPT, Claude, and click Fill in document. It runs entirely in your browser.

Using the import box instead

On freeinvoices.app, open the sidebar panel Import from ChatGPT, Claude and click Copy prompt.
Paste it into Codex, followed by your billing details or a pointer to the file in your repo, and ask for JSON only.
Copy the whole reply, code fences and all, into Paste the AI reply, and click Fill in document.

Privacy

With MCP, the invoice details Codex sends go to freeinvoices.app/mcp so the server can build the link and totals. They are not stored. The data in the link sits in the URL fragment after #data=, which browsers do not send to servers. Codex and OpenAI still see whatever files and text you give the agent, so check what is in the timesheet before you ask. The import box never leaves your browser.

Example prompts

“Read timesheet.json and create a FreeInvoices invoice for Acme Co. Use a separate line item per task and add 8% sales tax.”
“List the PRs merged into main since 2026-10-01 with `git log` and create an invoice with one line item per PR at $400 flat, due in 14 days.”
“Turn hours.csv into a quote instead of an invoice, in EUR, with 19% VAT labeled VAT.”
“Create a credit note for invoice 2026-014 for the 6 hours of code review we removed.”
“Make a receipt for the $250 hosting setup fee, marked as paid in full.”

FAQ

Do I need an experimental flag or a special Codex version?

The current Codex docs list no experimental flag for Streamable HTTP servers. codex mcp add with --url and a url entry in config.toml are documented. If your installed version lacks --url, update Codex.

Does the server need an API key or login?

No. The FreeInvoices MCP server has no authentication, so you do not use bearer_token_env_var or codex mcp login.

Can Codex build the #data= link itself?

No, and you should not ask it to. Models cannot reliably base64-encode a document. Only the MCP tool builds the link. Without MCP, use the import box.

Does it create the PDF for me?

No. The link opens the pre-filled invoice in your browser, and you click Download PDF there. The editor and PDF run in your browser.

Sources

FreeInvoices is independent and not affiliated with or endorsed by OpenAI Codex's maker. Product names are trademarks of their owners.