Unplain MCP

Your assistant writes the ebook or report. Unplain designs it and hands back a publish-ready PDF.

Unplain is a hosted Model Context Protocol server. Ask for a document and your assistant writes it, picks a design (or applies a brand you have saved), generates a cover, and exports a finished PDF with a composed cover, a table of contents built from the headings, real pagination and a closing call-to-action page. You never leave the chat, and you never open a design tool.

Two things follow from that, and they are the reason to use this rather than asking a model for a PDF directly:

• It comes out the same every time. Brand Themes are stored, so the tenth document matches the first. Your assistant can create one and reuse it.
• Revisions cost no tokens. Every document is a real project in your Unplain account, and the tools return an editor link. Fix a sentence by clicking it, not by asking the model to regenerate the file.

Unplain does not write your content, and through MCP it does not take file uploads: your assistant supplies the words as Markdown. Uploading a .docx or a .txt is a web app feature, not an MCP one.

• Endpoint: https://app.unplain.io/api/mcp
• Transport: Streamable HTTP
• Auth: Authorization: Bearer <api-key> (a bare Authorization: <api-key> is also accepted)
• Install: nothing to install
• Docs: https://unplain.io/mcp
• Pricing: included on every plan, free and Pro. https://unplain.io/pricing

This repository is documentation. The server is hosted, so there is no package to install and no source to run. Issues and questions are welcome here.

Publishing to the official MCP Registry: see PUBLISHING.md. The manifest is server.json.

---

Quick start

1. Get an API key

Create one at account settings. It is shown once. A free account works for everything below.

2. Add the server

Claude Code

claude mcp add --transport http unplain https://app.unplain.io/api/mcp \
  --header "Authorization: Bearer unp_your_key_here"

Full guide: https://unplain.io/mcp/claude-code

Codex

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

Full guide: https://unplain.io/mcp/codex

Anything else

Any client that can add a remote MCP server and send an Authorization header works. You need two values:

Server URL:  https://app.unplain.io/api/mcp
Header:      Authorization: Bearer unp_your_key_here

A client that only supports servers running on your own machine cannot connect yet.

3. Say hello

List the Brand Themes in my Unplain account and tell me which one is the default.

An empty list is still a success: the connection is live, you have not saved a theme yet.

4. Make something

Write a short ebook called "The Email Welcome Sequence Playbook" with an intro
and five chapters. Use my default Brand Theme, then export the PDF.

---

Tools

Twelve tools. Names and behaviour are current as of the version in CHANGELOG.md.

Tool	What it does
get_account	Report the plan this key belongs to and the limits that apply. Worth calling before writing anything long.
get_design_options	The font catalog, the built-in presets, and the allowed range of each typography and spacing setting.
list_brand_themes	List saved Brand Themes.
create_brand_theme	Save a new Brand Theme: colors, fonts, links.
update_brand_theme	Change a theme's name, colors, fonts or links.
create_ebook	Create a project from a title and Markdown.
list_ebooks	Find the caller's projects.
get_ebook	Read a project back as a structured outline.
update_ebook	Rewrite paragraphs, headings and lists, change cover copy and style, apply a theme, or replace the body.
generate_cover_image	AI cover artwork, drawn from the section headings or from your direction.
export_ebook	Render the designed PDF.
get_export_status	Poll a running export and get the download link.

Notes that matter in practice

• Edits are atomic and version-checked. An assistant cannot overwrite a change you made in the web app in the meantime; a stale write is rejected rather than applied over your work.
• Design can be described rather than specified. "A stark monochrome report" or "an elegant independent literary journal" resolves to real settings, chosen from what Unplain actually supports rather than guessed.
• Fonts outside the catalog are refused, not substituted. What you see in the app is what lands in the PDF.
• Cover generation uses your existing allowance, the same one the button in the app draws on. There is no separate MCP allowance. Overwriting an existing cover needs an explicit go-ahead, so a repeated request cannot silently spend a second generation.
• Download links are signed and expire. The project is saved, so export again rather than hoarding the URL.

---

Plans and limits

The MCP is an interface, not a tier. A key carries exactly the capabilities of the account behind it, and the same limits apply whether you work in the web app or through an assistant.

	Free	Pro
Content pages per exported PDF	5	Unlimited
Saved projects	5	Unlimited
Brand Themes	1	25
AI covers	1 lifetime	30 per period
"Made with Unplain" badge	Always	Removable

Cover, contents and call-to-action pages never count toward the page limit. Current pricing: https://unplain.io/pricing

---

Example prompts

See examples/prompts.md for a fuller set. A few to start:

Take the Markdown in notes.md and create an Unplain ebook called "Q3 Growth
Report". Use my default Brand Theme, then wait for the export and give me the
PDF link.

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.

Analyse the churn data in ./data, write it up as a report with an executive
summary, three findings and a recommendation, then create it in Unplain using
my "Acme" theme and export the PDF.

---

Keeping your key safe

Treat it like a password.

• Codex reads it from an environment variable, which keeps it out of config files.
• Claude Code's -s project writes a .mcp.json in the project root. Do not commit a real key in it. Use a placeholder and have each person supply their own; a key acts in the account it belongs to.
• Revoke from account settings. Revocation takes effect immediately. Keep one key per client so you can revoke one without disturbing the rest.

---

Troubleshooting

Symptom	Cause
Every tool call fails	The key is not reaching the server. The header must be Bearer (with the space) then the key, and the URL must end in /api/mcp with no trailing slash. A bad key returns 401, which most clients report as a failed connection.
Tools do not appear	Restart the client. New servers are picked up at session start.
Codex cannot find the key	It reads the environment at launch. Export it in your shell profile and start Codex from a shell that has it.
"No Brand Themes"	The connection works, you have not saved one. Your assistant can create one, or design from the built-in presets.
Export says the ebook is too long	Free exports up to 5 content pages. Shorten it or upgrade. The project is saved either way.
Too many requests	Per-account rate limits on creates and exports. Wait a minute.

More: https://unplain.io/mcp

---

Support

• Docs: https://unplain.io/mcp
• Email: info@unplain.io
• Issues: use this repository

License

Documentation and examples in this repository are MIT licensed. The Unplain service itself is governed by its terms and privacy policy.