Paperboy for OpenAI Agents SDK
Write, fact check and publish SEO articles from OpenAI Agents SDK
Attach Paperboy to an OpenAI Agents SDK agent so it can research, draft and fact check SEO articles from Python.
- Nothing publishes unless you say so
- The same fact check as the dashboard
- Or self-host it (AGPL-3.0, repo coming soon)
Set up
How do I add Paperboy to OpenAI Agents SDK?
You will connect Paperboy with MCPServerStreamableHttp and an Authorization header, then run an agent that can call its tools.
In Paperboy, open Settings and create an API key. It starts with pb_live_.
Install openai-agents and set PAPERBOY_API_KEY and your OpenAI key.
Save agent.py as shown.
Run python agent.py.
Check that the output lists your sites.
pip install openai-agents
export PAPERBOY_API_KEY=pb_live_YOUR_KEY
export OPENAI_API_KEY=YOUR_OPENAI_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 the script. Your site list in the output means the connection and key work.
How to remove it
Remove the server from mcp_servers and unset PAPERBOY_API_KEY.
What you get
What do Paperboy's eight tools do?
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.
Freesuggest_topicsReturns the next articles to write, each with the search data that is the reason for it.
1 creditwrite_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.
12 creditsget_articleReturns the article's status, its fact-check verdict and every source. Poll it after write_article until it reads published or needs_review.
Freecheck_claimsFact checks any public URL or pasted Markdown and returns each cited claim with the sources it was compared against.
2 creditspublish_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.
Freeget_performanceSearch Console clicks, impressions and average position for a site, by day and by article.
Freeget_queriesThe queries a site, or one article, appears for in Search Console. This is where page-two keywords show up.
Free
Try it
What can I ask OpenAI Agents SDK to do with Paperboy?
Plain requests. The tools each one uses are listed under it.
“Use Paperboy to list my sites, suggest topics for the main one, and write an article for the top topic.”
Uses
get_sitessuggest_topicswrite_article“Fetch my latest Paperboy draft with get_article and run check_claims on it. Tell me which claims need a source.”
Uses
get_articlecheck_claims“Ask Paperboy for my top search queries and page performance this month and summarize what to write next.”
Uses
get_queriesget_performance
Why
Why use Paperboy in OpenAI Agents SDK and not the dashboard?
The Python SDK's MCPServerStreamableHttp takes a url, a headers dict and a timeout. Paperboy's endpoint is Streamable HTTP, so the connection is a few lines.
Raise the timeout above the 5 second default, and have the agent start write_article and poll get_article, since an article takes a few minutes.
Compare
How does OpenAI Agents SDK compare with the dashboard?
Same engine, two ways in. Pick the one that fits how you already work.
| Feature | Dashboard | OpenAI Agents SDK | Source |
|---|---|---|---|
| Where you work | paperboyseo.com/app: sites, calendar, fact checks | Python SDK that attaches MCP servers to an Agent. | OpenAI Agents SDK docs: Model Context ProtocolRead Oct 30, 2026 |
| How it connects | Sign in and paste your site address. The first article is free. | Remote MCP. The Python SDK offers MCPServerStreamableHttp, whose params take a url, a headers dict and a timeout, and a HostedMCPTool for servers the Responses API reaches itself. | OpenAI Agents SDK docs: Model Context ProtocolRead Oct 30, 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 OpenAI Agents SDK 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
What should I know about OpenAI Agents SDK specifically?
Quirks of this client that can cost you an afternoon.
The docs say to pass credentials in the headers dict, not in the URL.
The docs give a 5 second default connection timeout, so the example raises it. Paperboy tool calls such as write_article can take minutes, so start them and poll get_article.
The SDK docs require the mcp package, in the range they state.
FAQ
Questions about Paperboy and OpenAI Agents SDK
Does the Agents SDK support remote MCP with custom headers?
Yes. MCPServerStreamableHttp params take a url, a headers dict and a timeout.
Can I use HostedMCPTool instead?
The docs show it with a server_url for servers the Responses API reaches. They do not show an Authorization option in the excerpt checked, so this page uses MCPServerStreamableHttp.
Is there a TypeScript version?
This page covers the Python SDK only. The TypeScript SDK was not checked.
Where do I get the key?
In Paperboy, open Settings and create an API key. It starts with pb_live_.
How much does it cost to use Paperboy from OpenAI Agents SDK?
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.
Can OpenAI Agents SDK publish to my site without asking me?
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
Where do these facts come from?
Where do these facts come from?
Everything about OpenAI Agents SDK comes from the pages below, read on Oct 30, 2026. Tools change their docs, so check there if a step does not match. If we got something wrong, write to hello@paperboyseo.com.
- OpenAI Agents SDK docs: Model Context Protocolread Oct 30, 2026
Keep going
Where do I go next?
Ready to run your SEO desk from OpenAI Agents SDK?
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).