unplain-mcp

# 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](https://modelcontextprotocol.io)
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](https://unplain.io) 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](PUBLISHING.md).
> The manifest is [server.json](server.json).

---

## Quick start

### 1. Get an API key

Create one at [account settings](https://app.unplain.io/account#api-keys). It is
shown once. A free account works for everything below.

### 2. Add the server

**Claude Code**

```bash
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**

```bash
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](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](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](https://app.unplain.io/account#api-keys).
  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](https://unplain.io/terms) and
[privacy policy](https://unplain.io/privacy).