Paperboy for Codex
Give Codex a plain job such as write and fact check the next article, and read the verdict in the same session.
Set up
You will put your Paperboy key in an environment variable and register paperboy as a Streamable HTTP server that reads it as a bearer token.
In Paperboy, open Settings and create an API key. It starts with pb_live_.
Export the key as PAPERBOY_API_KEY in the shell that launches Codex.
Run the codex mcp add command above, or add the [mcp_servers.paperboy] table to ~/.codex/config.toml. A project-scoped .codex/config.toml also works in trusted projects.
Start codex and type /mcp to see your active MCP servers.
Ask Codex to use a Paperboy tool, for example: list my sites with get_sites.
export PAPERBOY_API_KEY=pb_live_YOUR_KEY
codex mcp add paperboy --url https://paperboyseo.com/mcp --bearer-token-env-var PAPERBOY_API_KEYReplace pb_live_YOUR_KEY with a key from Settings, API keys, and never commit it. The MCP docs list every client we cover.
How to tell it worked
Run codex mcp list to see configured servers. Inside the codex terminal UI, type /mcp to see active MCP servers and their tools.
How to remove it
Run codex mcp remove paperboy, or delete the [mcp_servers.paperboy] table from config.toml. To keep it but turn it off, set enabled = false.
What you get
Eight tools, the same engine as the dashboard. Reads are free. A pack is $20 for 100 credits; see how credits work.
get_sitesLists your sites with plan, publishing method and whether Search Console is connected. Every other call starts from a site id.
suggest_topicsReturns the next articles to write, each with the search data that is the reason for it.
write_articleStarts a fact-checked article and returns an id at once. The run takes a few minutes. It does not publish unless you pass publish: true.
get_articleReturns the article's status, its fact-check verdict and every source. Poll it after write_article until it reads published or needs_review.
check_claimsFact checks any public URL or pasted Markdown and returns each cited claim with the sources it was compared against.
publish_articlePublishes an article that passed the fact check to the site's publishing target. It changes the live site, so the agent should ask first.
get_performanceSearch Console clicks, impressions and average position for a site, by day and by article.
get_queriesThe queries a site, or one article, appears for in Search Console. This is where page-two keywords show up.
Try it
Plain requests. The tools each one uses are listed under it.
“Use the paperboy MCP server: call get_sites, then get_performance for my main site and tell me which pages lost clicks over the last month.”
Uses get_sitesget_performance
“Call get_queries and suggest_topics, pick the topic with the best chance to rank, run write_article for it, and save the markdown into docs/blog.”
Uses get_queriessuggest_topicswrite_article
“Fetch the draft with get_article, run check_claims, and list every claim that needs a source. Do not publish until I say so.”
Uses get_articlecheck_claims
Why
Codex shares one config.toml across its CLI, its IDE extension and the ChatGPT desktop app, so you register Paperboy once and every surface can use it. The key stays in an environment variable. The file holds only the variable name.
Plan for the slow call. Codex gives a tool 60 seconds by default, and write_article returns an id at once for that reason. Poll get_article until the status settles. You can also set publish_article to prompt, so Codex always asks before it changes your live site.
Compare
Same engine, two ways in. Pick the one that fits how you already work.
| Feature | Dashboard | Codex | Source |
|---|---|---|---|
| Where you work | paperboyseo.com/app: sites, calendar, fact checks | Coding agent for your terminal, IDE extension, and cloud tasks. | Codex docs: Model Context Protocol (developers.openai.com/codex/mcp redirects here)Read Oct 29, 2026 |
| How it connects | Sign in and paste your site address. The first article is free. | Remote MCP. Codex supports Streamable HTTP MCP servers with bearer token authentication, static headers, and env-sourced headers. | Codex docs: Model Context Protocol (developers.openai.com/codex/mcp redirects here)Read Oct 29, 2026 |
| Does it publish without asking? | Your choice: autopilot, or approve each article by email. | No. write_article defaults to publish: false, and the tool descriptions tell the agent to ask first. | MCP docsPaperboy docs |
| Fact check | Every number and cited sentence is compared with the saved text of its source. An article that fails gets one rewrite, then is held for you. | The same engine and the same check. The verdict comes back to the agent: verified, or held with the reason. | How the check worksPaperboy docs |
| What it costs | Plans from $49 a month per site. The first article is free, no card. | Credits: 12 per article, 1 per topic suggestion, 2 per fact check. $20 buys 100. | CreditsPaperboy docs |
| Search Console | Optional read-only Search Console connection. It picks topics from your impressions and reports clicks per article. | get_performance and get_queries return the same read-only data, by day, by article and by query. | Security and dataPaperboy docs |
Facts about Codex come from the pages linked in the Source column, read on the date shown. Tools change their docs, so confirm there if a step does not match.
Honest notes
Quirks of this client that can cost you an afternoon.
One config for every Codex surface. The CLI, the IDE extension, and the ChatGPT desktop app share the same MCP configuration for the same Codex host, so you set Paperboy up once. The default file is ~/.codex/config.toml, and .codex/config.toml in a project works for trusted projects only.
The key is read from an environment variable, not stored in config.toml. The bearer_token_env_var setting holds only the variable name. The IDE extension form (gear menu, MCP servers, Add server) asks only for a name and a URL, so use the CLI or config.toml when you need the header.
Timeouts and approvals are per server. The defaults are startup_timeout_sec = 10 and tool_timeout_sec = 60, so raise tool_timeout_sec if a long Paperboy call such as write_article times out. Use tools.<tool>.approval_mode to make Codex prompt before a specific tool such as publish_article.
FAQ
Run codex mcp add paperboy --url https://paperboyseo.com/mcp --bearer-token-env-var PAPERBOY_API_KEY after exporting the key. Codex sends the variable's value as a bearer token in the Authorization header.
Yes. The docs say the ChatGPT desktop app, Codex CLI, and IDE extension share MCP configuration for the same Codex host, so a server you add once appears in each client.
Yes. Use http_headers for static header values or env_http_headers to fill a header from an environment variable. Bearer tokens through bearer_token_env_var are the simplest route for Paperboy.
Run codex mcp list, or type /mcp in the codex terminal UI to list active MCP servers and their tools.
The tools that read cost nothing. Suggesting topics costs 1 credit, writing a fact-checked article costs 12 credits (refunded if the run fails) and a fact check on its own costs 2 credits. A pack is $20 for 100 credits.
Only if you let it. write_article defaults to publish: false, so a finished article waits for a human, and the tool descriptions tell the agent to ask before publishing. You can also give the agent a read-only key.
Sources
Everything about Codex comes from the pages below, read on Oct 29, 2026. Tools change their docs, so check there if a step does not match. If we got something wrong, write to hello@paperboyseo.com.
Keep going
Add the MCP server, ask for a topic, and read the fact check before anything goes live.
claude mcp add --transport http paperboy https://paperboyseo.com/mcp --header "Authorization: Bearer pb_live_..."npx @paperboyseo/cli coming soonPrefer the dashboard? Write my first article free. Prefer to run it yourself? Self-host it (repo coming soon).