Unplain MCP
Create publish-ready PDFs without leaving your AI chat
MCP is a simple standard that lets an AI assistant use another app on your behalf. Connect Unplain once, and you can ask Claude or Codex to write a guide and hand you back a designed, on-brand PDF: no copying drafts into an editor, no manual formatting.
About ten minutes from key to first PDF. Works on the free plan.
What you'll need
-
An Unplain account
Free is enough to follow this whole guide.
-
An API key
One click in your account settings. Step 1 below.
-
A supported client
Claude Code or Codex, installed and signed in.
Generate an API key
The key is how your AI client proves it is allowed to act in your Unplain account. You create it once and paste it into your client.
- 1 Open Unplain and go to Account settings, then the API keys section.
- 2 Click Create API key. Naming it after the client (for example "Claude Code") makes it easy to revoke the right one later.
- 3 Copy the key straight away and keep it somewhere safe, like a password manager.
Your key looks like this
unp_••••••••••••••••••••
It is shown once, at the moment you create it, and never again. If you lose it or think it has leaked, revoke it from the same page and create a new one: revoking takes effect immediately. You can keep several keys at the same time, one per client.
Connect your AI client
Every client asks for the same two things: the Unplain server address, and your key. Pick yours below.
Run this in your terminal, with your own key in place of the placeholder:
claude mcp add --transport http unplain https://app.unplain.io/api/mcp \
--header "Authorization: Bearer unp_your_key_here"
That is the whole setup. To share the connection with a team on a
specific project instead, add -s project
to the command, which writes a .mcp.json
file in the project root. Claude Code asks each teammate to
approve that server the first time they open the project:
{
"mcpServers": {
"unplain": {
"type": "http",
"url": "https://app.unplain.io/api/mcp",
"headers": {
"Authorization": "Bearer unp_your_key_here"
}
}
}
}Check it worked
Run claude mcp list
in your terminal. Unplain should come back as
Connected. Inside a
Claude Code session, /mcp
shows the same thing.
Codex reads your key from an environment variable, so it never sits in a config file. Set it, then add the server:
export UNPLAIN_API_KEY="unp_your_key_here"
codex mcp add unplain \
--url https://app.unplain.io/api/mcp \
--bearer-token-env-var UNPLAIN_API_KEY
Add that same export line to your shell profile (for example
~/.zshrc), so the key is still there in a
new terminal. The command writes this into
~/.codex/config.toml, and you can add it by
hand instead if you prefer:
[mcp_servers.unplain]
url = "https://app.unplain.io/api/mcp"
bearer_token_env_var = "UNPLAIN_API_KEY"Check it worked
Restart Codex, then run
codex mcp list.
Unplain should appear with its status set to
enabled and its auth
shown as a bearer token.
Unplain runs a remote MCP server over HTTP, so any client that can add a remote server and send a custom header will work. These are the only two details you need:
Server URL: https://app.unplain.io/api/mcp
Header: Authorization: Bearer unp_your_key_hereA client that only supports servers running on your own machine, or one that cannot send an Authorization header, cannot connect to Unplain yet. Sign-in with your Unplain account instead of a key is on the roadmap, and will widen that list.
Say hello
Before creating anything, run one harmless prompt to prove the connection works.
Show me the Brand Themes available in my Unplain account.What you should see
Your assistant asks for permission to use an Unplain tool (allow it), then lists your themes with their names and colors, and points out which one is the default. If you have not saved a Brand Theme yet, you will get an empty list. That is still a success: the connection is live, there is simply nothing to show yet.
Create your first PDF
Paste this in and watch it work. Change the topic to anything you like.
Create an Unplain ebook called "The 7-point landing page audit".
First list my Brand Themes and use my default one.
Write a short introduction and seven sections, one per audit point,
each with a heading and two or three paragraphs.
Create the project, then wait for the PDF export to finish and give me
both the download link and the editor link.On the free plan, ask for three or four sections instead: free exports cover up to five content pages, and the cover, contents and CTA pages are not counted.
Your assistant writes the content
It drafts the ebook as Markdown, then sends it to Unplain along with the Brand Theme you asked for.
Unplain builds and renders it
The project is saved to your account with a cover, a table of contents, page numbers and a closing call-to-action page. Rendering happens in the background and a short ebook is usually ready in a few seconds.
You get two links
A download link for the finished PDF, valid for about an hour, and an editor link that opens the project in Unplain whenever you want to change something.
If your assistant reports the export as queued and then stops, just ask it to check again. Rendering is asynchronous, so it may need one more nudge to fetch the finished file.
What the Unplain MCP can do
You never have to describe any of this to your assistant. It discovers what Unplain offers as soon as it connects, and works out when to use it.
Your Brand Themes
Your assistant can list the Brand Themes saved in your account, with their colors and fonts, and style a new ebook with the one you pick.
Real Unplain projects
Every ebook it creates is a normal project in your account. You get an editor link back, so you can open it and keep working by hand.
Markdown in, design out
Headings, lists, bold, links, quotes and tables all carry over. Your assistant writes the Markdown; Unplain does the layout.
Cover, contents and CTA
Each PDF gets a designed cover (title, subtitle, author), a table of contents built from your headings, page numbers and a closing call-to-action page.
PDF export
Ask for the finished file and Unplain renders it in the background. Your assistant waits for it and hands you a download link.
Editing what already exists
Your assistant can read back an ebook you already have, change a single paragraph, heading or list, restyle the cover, apply a different Brand Theme, and export it again. It does not have to start over.
Careful about your work
If you edited the ebook in Unplain while your assistant was working on it, the change is refused rather than applied on top of yours. Your assistant re-reads the current version and tries again.
Safe retries
If a request is repeated, your assistant can reuse the same project instead of creating a duplicate, so a hiccup never clutters your dashboard.
Your plan, understood
Your assistant can check which plan you are on and what it allows before it starts writing, so a free account gets an ebook that fits the free plan rather than one that cannot be exported.
Prompts worth stealing
Every one of these works with the tools available today.
See your Brand Themes
List the Brand Themes in my Unplain account and tell me which one is the default.Turn a Markdown file into a PDF
Take the Markdown in notes.md and create an Unplain ebook called "Q3 Growth Report" by me, Adam. Use my default Brand Theme, then wait for the export and give me the PDF link.Write and design a branded ebook
Write a short ebook called "The Email Welcome Sequence Playbook" with an intro and five chapters, each about 300 words. List my Brand Themes first and use the one called "Main brand". Create it in Unplain and export the PDF.Create a draft without exporting
Create this as an Unplain draft only, without rendering a PDF, and give me the editor link so I can polish the cover myself.Check on a running export
Check whether that Unplain export has finished, and give me the download link when it is ready.Fix something in an ebook you already have
Open my Unplain ebook "Q3 Growth Report", read the outline, rewrite the introduction so it opens with a concrete number instead of a general claim, then export a fresh PDF.Restyle a cover without touching the writing
Take my Unplain ebook "The Email Welcome Sequence Playbook", switch it to the bold cover style, set the subtitle to "A practical five-part guide", apply my "Main brand" theme, and export it again.If something goes wrong
The client says it cannot connect, or every tool call fails
Nine times out of ten the key is not reaching the server. Check that the header value starts with "Bearer " (with the space) followed by your key, that the key has not been revoked, and that the URL ends in /api/mcp with no trailing slash. A wrong or missing key gets you a 401 response, which most clients report as a failed connection.
Codex cannot find the key
Codex reads the key from an environment variable at launch, not from its config file. Make sure UNPLAIN_API_KEY is exported in the shell you start Codex from, and add it to your shell profile (for example ~/.zshrc) so it survives a new terminal window.
The tools do not show up
Restart the client after adding the server. Claude Code picks up new servers when you start a new session, and Codex when you relaunch it. Then ask your assistant what Unplain tools it has, or run the list command shown in your tab.
It says I have no Brand Themes
That means the connection works, you simply have not saved one yet. Open Unplain, set your colors, fonts and logo, and save the theme. Your assistant will see it on the next request. Without a theme it uses Unplain's standard styling.
The export said the ebook is too long for the plan
The free plan exports up to five content pages per PDF (the cover, contents and CTA pages do not count). Shorten the ebook, or upgrade to Pro for unlimited length. The project stays in your account either way, so nothing you wrote is lost. To avoid this, ask your assistant to check your Unplain plan before it starts writing.
The download link stopped working
PDF links are signed and expire about an hour after they are created, and the rendered file is cleared after a day. The project itself is saved, so open it in Unplain and export again, or ask your assistant to create it again.
It says there were too many requests
There are per-account limits on how many ebooks and exports you can start each minute, to keep renders fast for everyone. Wait a minute and ask again.
Still stuck after that? Email info@unplain.io with the client you are using and what you tried, and we'll help you finish the setup.
Keeping your key safe
- A key can do anything you can do in Unplain: create ebooks, use your Brand Themes, and export PDFs against your plan's limits. Treat it like a password.
- Never commit a key to a repository, paste it into a shared document, or leave it visible in a screenshot or screen share.
- Prefer an environment variable when your client supports one, as Codex does.
- Use a separate key per client, so revoking one does not disconnect the others.
- If a key might have leaked, revoke it in your account settings and create a new one. Revoking is instant.
What it cannot do yet
- Claude Code and Codex are the clients we have tested end to end. Others may work, but we will not claim they do until we have checked.
- Your assistant can create new ebooks, not open or re-export ones you already have. Use the editor link for those.
- Images are not supported in the content it sends, and it cannot generate or set a cover image. You can add both in the editor.
- The call-to-action page is created with placeholder text, ready for you to edit in Unplain.
- Documents are capped at about 250,000 characters, which is far longer than a normal ebook.
- PDF rendering is asynchronous: your assistant starts the export and then checks back for the file.
Common questions
What is MCP?
MCP (Model Context Protocol) is an open standard that lets an AI assistant use an outside app. Once you connect Unplain to your assistant, it can create ebooks and export PDFs in your account without you copying anything between windows.
Which AI clients can connect to Unplain?
Claude Code and Codex are supported and verified today. Any other client that can connect to a remote MCP server over HTTP and send a custom Authorization header will work too, using the same URL and key.
Do I need a paid plan to use the Unplain MCP?
No. The MCP is included with every Unplain account, free or Pro. It is not a separate product and there is nothing extra to buy. A free account can create an API key and export PDFs of up to five content pages, with the Made with Unplain badge. Pro removes the length limit and the badge.
Do my plan limits change when I use an AI assistant?
No. The MCP is another way into the same Unplain, so you get exactly the capabilities of the plan you already have. Ebooks your assistant creates count toward your saved projects, and their PDFs follow the same length limit and branding rules as ones you export from the app. Your assistant can also check your plan and its limits before it writes, so it can size the ebook to fit.
Does the AI write the ebook, or does Unplain?
Your assistant writes the words. Unplain designs and publishes them: cover, table of contents, pagination, brand colors and fonts, and a closing call-to-action page.
Is my API key safe to put in a config file?
Treat it like a password. Codex reads it from an environment variable, which keeps it out of the config file. Wherever you store it, never commit it to a repository, and revoke it from your account page if it leaks.
New to Unplain? See what it does, how it works with Claude drafts, or what the free plan covers.