# MintPage docs

> **For AI agents:** MintPage is a remote MCP server at `https://mintpage.ai/mcp` (Streamable HTTP, stateless, no key needed to try). Without a key you're a guest: 3 pages a day, each lasting 24 hours, so don't waste one. Check the connection with `get_account`: it doesn't use a page. Never publish a test page. If your user hasn't said what to publish, ask them. Reply with the page URL, and only a URL MintPage returned: if a call fails or you can't reach MintPage, say so instead of building a link. Pages are public, with no passwords, and can't run JavaScript. No MCP? `POST https://mintpage.ai/api/publish`, see [Use it without MCP](https://mintpage.ai/docs#http). No tools at all? Give your user a link, see [No tools: give a link](https://mintpage.ai/docs#link).

## Quick start

1. **Add MintPage to your AI.** Server URL: `https://mintpage.ai/mcp`. No sign-in, no key. Find your app in [Add MintPage to your app](https://mintpage.ai/docs#connect).
2. **Check that it works.** Ask your AI: *"Check my MintPage account."* It calls `get_account` and shows your plan and how many pages you have left today. No page is used.
3. **Ask for a page.** *"Publish this as a page: …"* or *"Turn your last answer into a page."* You get back a link like `https://mintpage.ai/p/x2rcwq89`.

Your app can't add MCP servers? Paste [the prompt](https://mintpage.ai/docs#prompt) instead.

## Add MintPage to your app

Every app needs the same three things: the URL `https://mintpage.ai/mcp`, the transport **Streamable HTTP** (often just called "HTTP"), and **no authentication**. With a [free key](https://mintpage.ai/docs#key), add the header `Authorization: Bearer mp_…`, or use `https://mintpage.ai/mcp/mp_…` as the URL in apps that can't set headers.

### Claude Code

```bash
claude mcp add --transport http mintpage https://mintpage.ai/mcp
```

With a key, add `--header "Authorization: Bearer mp_…"`. If you write `.mcp.json` by hand, include `"type": "http"`: without it the server is skipped.

### Claude.ai and Claude Desktop

**With your account (recommended):** **Customize → Connectors → + Add → Add custom connector.** Name: MintPage. URL: `https://mintpage.ai/mcp/account`. Claude opens a MintPage page: enter your email, open the sign-in link, and press **Allow**. No key to copy; new addresses get a free account when the link is opened. Then turn it on in a chat with **+ → Connectors**.

**As a guest:** use the URL `https://mintpage.ai/mcp` with Authentication **No sign in** (3 pages a day, 24 hours each).

To disconnect, remove the connector in Claude. Its access stops within a day at most; email mintpage@agentmail.to to cut it off at once.

### ChatGPT

On chatgpt.com: **Plugins → + → Add custom MCP server**. Server URL: `https://mintpage.ai/mcp/account`, Authentication: **OAuth**. ChatGPT sends you to MintPage to sign in with your email and press **Allow**. Then type **@** in a chat to use it. As a guest, use `https://mintpage.ai/mcp` with **No authentication** instead.

### Cursor

`.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for all projects:

```json
{ "mcpServers": { "mintpage": { "url": "https://mintpage.ai/mcp" } } }
```

With a key, add `"headers": { "Authorization": "Bearer mp_…" }` next to `"url"`.

### VS Code (GitHub Copilot)

`.mcp.json` at the root of your workspace:

```json
{ "mcpServers": { "mintpage": { "type": "http", "url": "https://mintpage.ai/mcp" } } }
```

The older `.vscode/mcp.json` file uses `"servers"` instead of `"mcpServers"`, with the same entry inside.

### Windsurf (Devin Desktop)

In Cascade: **… → MCPs → Open MCP config file**, then add:

```json
{ "mcpServers": { "mintpage": { "serverUrl": "https://mintpage.ai/mcp" } } }
```

### Gemini CLI

```bash
gemini mcp add --transport http mintpage https://mintpage.ai/mcp
```

In `settings.json`, the field is `"httpUrl"`, not `"url"` (`"url"` means the older SSE transport and won't connect).

### OpenAI Codex CLI

```bash
codex mcp add mintpage --url https://mintpage.ai/mcp
```

With a key, add `bearer_token_env_var = "MINTPAGE_API_KEY"` under `[mcp_servers.mintpage]` in `~/.codex/config.toml` and put the key in that environment variable.

### Lovable

**Connectors → + → MCP server.** Server URL: `https://mintpage.ai/mcp` (with a key: `https://mintpage.ai/mcp/mp_…`). Authentication: **No authentication**. Use it from the project chat.

### Any other app

Add a remote MCP server with the URL `https://mintpage.ai/mcp`, transport Streamable HTTP, no authentication.

## The prompt (any AI)

For apps without MCP settings, or to put in an agent's instructions. Also at [/agent.txt](https://mintpage.ai/agent.txt).

```text
I want you to use MintPage to publish a page for me.
1. Read: https://mintpage.ai/docs.md
2. Use: https://mintpage.ai/mcp (mind the free limits: 3 pages a day)
3. Give me: the shareable URL
```

## No tools: give a link

A chat AI that can't call MCP or HTTP (ChatGPT or Gemini without tools, a private window, no account) can still share: it writes a link that carries the page, and the user publishes it.

```text
https://mintpage.ai/new#t=Weekly%20report&md=%23%20Weekly%20report%0A%0AShipped%2014%20of%2016%20items.
```

`t` is the title and `md` the Markdown (or `html` for HTML), both URL-encoded: spaces as `%20`, new lines as `%0A`, `#` as `%23`. Put the link in a code block: some chat apps (Gemini, for one) turn links they can't verify into Google searches, and a code block keeps it intact. The user opens the link, or pastes it at [mintpage.ai/new](https://mintpage.ai/new), sees a preview, presses **Publish** and gets the shareable URL. Everything after `#` stays in their browser until they publish. A link carries a few thousand characters; for a longer answer, tell the user to paste it at [mintpage.ai/new](https://mintpage.ai/new).

## Get a free key (optional)

Without a key you're a guest: 3 pages a day, each lasting 24 hours. A free key from [/start](https://mintpage.ai/start) (sent by email) gives you 10 live pages that last 7 days, view stats, and lets your agent edit, pause and delete its pages. You can create more keys from the [dashboard](https://mintpage.ai/dashboard). Three ways to send a key:

- Header `Authorization: Bearer mp_…` (best).
- In the URL: `https://mintpage.ai/mcp/mp_…`, for apps that can't set headers (Claude.ai, ChatGPT, Lovable).
- Query parameter `?key=mp_…`.

A key leaked? See [Security](https://mintpage.ai/security#exposed).

## What to ask your agent

- *"Check my MintPage account."* Shows your plan and pages left; publishes nothing.
- *"Publish this as a page and give me the link."* Calls `publish_page`.
- *"Keep the same page updated."* Reuses the `page_id` with `update_page`: same link, new content (needs a key).
- *"Make it dark."* `theme: "ink"`. Other themes: `paper` (light) and `terminal` (dark, monospace).
- *"Expire it after the meeting."* `expires_in_hours: 3`.
- *"Keep this one up for good."* `mint_page` spends one mint (on Pro, every page is already permanent).

## Tools

| Tool | Arguments | Notes |
|---|---|---|
| `publish_page` | `title`, `content`, `format` (markdown or html), `theme` (paper, ink, terminal), `byline`, `slug` (Pro), `expires_in_hours` | Returns `url` and `page_id` (plus `live_url` on Pro). Works for guests. |
| `get_account` | none | Plan, usage, limits, upgrade link. Works for guests; publishes nothing. |
| `update_page` | `page_id` + any of the above | Keeps the URL, unless you pass a new `slug` (Pro or minted pages): then the old link says "revoked" and can't be reused. Key required. |
| `list_pages` | none | Newest first, with views and expiry. Key required. |
| `get_page_stats` | `page_id` | Total views, last view, 30-day daily series. Key required. |
| `pause_page` | `page_id`, `paused` (true or false) | Hides a page behind the same URL ("paused") for everyone but the signed-in owner. Reversible. Key required. |
| `revoke_link` | `page_id` | Turns off the current link and gives the page a new random one; the old URL says "revoked" for good. Key required. |
| `delete_page` | `page_id` | Irreversible; the URL shows "removed". Key required. |
| `mint_page` | `page_id` | Spends one mint to make that page permanent with Pro limits (no expiry, no badge, 2 MB, custom slug, indexable); it no longer counts toward your live pages. Once per page; free if already minted or on Pro. Key required. |
| `list_comments` | `page_id`, `include_resolved`, `include_pictures` | Comments from the page's live session (Pro): text, author, box, the page text and HTML inside the box, whether it was written on the current version, and a picture of each open comment's box (box outlined in red). |
| `resolve_comment` | `comment_id`, `note` | Marks a comment done; the note shows in the session. |
| `rotate_api_key` | none | Returns a new key once and revokes the one used for the call. |

## Live sessions (Pro)

Share a page as a private live session: the people you invite watch it change the moment you or your agent edit it, without reloading.

1. In the [dashboard](https://mintpage.ai/dashboard), open **Live session** on a page and invite people by email. Each one gets a personal link.
2. They open it once in their browser and watch at the page's live address (its link plus `/live`). A **Live** badge shows they're connected.
3. Keep editing with `update_page`: each change shows up on their screen within a few seconds.
4. The panel shows the last change and who is watching now. **Revoke** turns someone's access off within seconds; re-inviting an address replaces its old link.

**Comments.** Anyone in the session can click **Comment**, drag a box around part of the page and write what should change. The boxes stay on the page for everyone in the session, numbered, with a comments list beside it. Ask your agent to pick them up: `list_comments` returns each comment with the box, the page text and HTML inside it, who wrote it, and a picture of the boxed area so the agent sees exactly what was pointed at; after changing the page, `resolve_comment` closes it with a short note everyone sees. The × on a box (or in the list) removes a comment: people remove their own, the page owner can remove any.

Only you (signed in) and the people you invited can open the live view. The page's normal link still works for anyone who has it; **pause** the page to keep it to your invitees only. Tool results include `live_url` on Pro.

## What a page can contain

**Markdown** is GitHub-flavored: tables, task lists, fenced code, strikethrough, autolinks. **HTML** is cleaned every time the page is served: scripts, forms, iframes, event handlers and external stylesheets are removed. Inline `style` attributes, `<style>` blocks (no `@import` or `url()`), images and inline SVG stay. Tailwind classes need the Tailwind script, so they won't style anything: write the CSS in a `<style>` block. Page CSS applies only to the page's content box: rules for `html`, `body` or `:root` style that box, and nothing can restyle the MintPage frame around it. To make a page wider, set `.mp-wrap { max-width: 1100px }`. When something is removed, the result lists it in `warnings`.

There are no passwords or private pages: anyone with the link can open a page, and `publish_page` refuses a `password` field rather than ignoring it.

No JavaScript still leaves a lot: bar charts from `div`s with an inline width, `<progress>` and `<meter>`, line charts in inline SVG, collapsible sections with `<details>`, layouts with CSS grid, dark-mode media queries, and clickable prototypes where each button links to `#screen-2` and CSS shows the screen the link points at. See the [showcase](https://mintpage.ai/showcase): every page there uses only what `publish_page` accepts.

Every page gets a link preview (title, description and a 1200×630 image) for Slack, X and LinkedIn. Pages are responsive and print cleanly.

## Use it without MCP (HTTP)

The simplest call is a plain JSON POST to `https://mintpage.ai/api/publish`. It takes the same fields as `publish_page` and returns the same result:

```bash
curl -sS https://mintpage.ai/api/publish \
  -H 'Content-Type: application/json' \
  -d '{"title":"Weekly report","content":"# Weekly report\n\nShipped 14 of 16 items.","theme":"paper"}'
```

The answer has `url` and `page_id` (HTTP 201). With a key, add `-H 'Authorization: Bearer mp_…'`. Fields it doesn't know, such as `password`, are refused with HTTP 400 and nothing is published. Errors come back as `{"error": "…"}`: 429 when you're over the page limit, 413 when the content is too large.

MintPage also speaks JSON-RPC 2.0 (the MCP protocol) over a plain POST to `https://mintpage.ai/mcp`. Send the header `Accept: application/json, text/event-stream`. There's no session and no handshake: responses are plain JSON, so a cron job or a curl one-liner works.

Check the connection (publishes nothing):

```bash
curl -sS https://mintpage.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_account","arguments":{}}}'
```

The tool result is JSON text in `result.content[0].text`. To list every tool and its arguments, send `"method":"tools/list"`.

## Limits

| | Guest | Free key | Pro |
|---|---|---|---|
| Live pages | 3 per 24 h | 10 | 500 |
| Page size | 250 KB | 1 MB | 2 MB |
| Lifetime | 24 h | up to 7 days | forever, or what you set |
| Custom slugs | no | no | yes |
| Stats | no | yes | yes |
| Badge on page | yes | yes | no |
| Search engines | hidden | hidden | indexable |

All plans: 120 requests per minute per IP. A **minted page** gets the Pro column on any plan and doesn't count toward the live-page limit.

## Billing

Pro is $5/month or $39/year, from the [dashboard](https://mintpage.ai/dashboard). Pay with the same email as your key and the upgrade applies within seconds. Cancelling keeps Pro until the end of the paid period; your pages stay online afterwards and count toward the Free limit.

**Peppermint pack (pay per mint):** 10 mints for $5, one time, from [billing](https://mintpage.ai/billing). Nothing renews and mints don't expire. One mint makes one page permanent with Pro limits: press **Make permanent** on the dashboard or ask your agent to call `mint_page`.

## Dashboard API (REST)

The dashboard uses a small JSON API. Authenticate with `Authorization: Bearer mp_…` (or the session cookie from [/login](https://mintpage.ai/login); cookie requests must come from mintpage.ai).

| Endpoint | Does |
|---|---|
| `GET /api/me` | Plan, limits, live pages, `mint_credits` and your pages (each with `minted`). |
| `POST /api/pages/:id/pause` · `resume` · `revoke` · `delete` | Same as `pause_page`, `revoke_link`, `delete_page`. |
| `POST /api/pages/:id/mint` | Same as `mint_page`. Returns `outcome` (`minted`, `already_minted` or `pro`), `charged` and `mint_credits`. With no mints left: `402` and `code: "no_mints"`. |
| `GET /api/billing` | Plan, subscription, mint balance and mint history. |
| `POST /api/billing/peppermint` | Returns a Stripe Checkout `url` for a Peppermint pack. |

## Connect with sign-in (OAuth)

Apps that support OAuth for MCP (Claude, ChatGPT, MCP Inspector) can connect to `https://mintpage.ai/mcp/account` instead of using a key:

- Without a token it answers `401` with `WWW-Authenticate: Bearer resource_metadata="https://mintpage.ai/.well-known/oauth-protected-resource/mcp/account"`.
- Authorization server: `https://mintpage.ai` ([metadata](https://mintpage.ai/.well-known/oauth-authorization-server)). Dynamic client registration and client ID metadata documents are both supported; PKCE with S256 is required.
- Sign-in is the usual email link, followed by a consent screen that names the app and the site you'll be sent back to.
- Access tokens last 24 hours; refresh tokens last 90 days and change on every use. A refresh token used twice ends the connection.
- A connection can do what an API key can do on your account: publish, update, list, pause, revoke and delete your pages. It can't change your plan or pay for anything.

## Troubleshooting

- **"Guests can mint 3 pages per 24 hours."** Wait, or get a [free key](https://mintpage.ai/docs#key) for 10 live pages.
- **"Content is … bytes; the Guest plan allows 250000."** Split the page, or use a key (1 MB) or Pro (2 MB).
- **"Invalid or revoked API key." (HTTP 401)** Check the key, or remove it to use guest mode. Rotated keys stop working.
- **The app lists MintPage but the AI doesn't use it.** In Claude.ai, turn the connector on in the chat (**+ → Connectors**). In ChatGPT, type **@** and pick it. Or ask by name: *"Use MintPage to…"*.
- **Gemini CLI won't connect.** Use `"httpUrl"`, not `"url"`, in `settings.json`.
- **Claude Code ignores the server in `.mcp.json`.** Add `"type": "http"`.
- **The page looks unstyled or blank.** Pages can't run JavaScript, so a Tailwind or React page loses its styling. Read `warnings` in the result, move the CSS into a `<style>` block, and send rendered HTML, not component code.
- **"MintPage has no password protection or private pages."** You sent a `password` (or similar) field. Remove it; every page is public to anyone with the link.
- **A page says "expired".** Guest pages last 24 hours and free pages 7 days. Mint it, or use Pro, to keep pages up.

How pages are kept safe, and how to report abuse or a vulnerability: [Security](https://mintpage.ai/security).

---
Human-readable version: https://mintpage.ai/docs · Short index: https://mintpage.ai/llms.txt