> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paperjoy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Paperjoy MCP server for Claude and AI assistants

> Let Claude or another AI assistant write, send, and track handwritten postcards for you.

Paperjoy runs a remote [MCP](https://modelcontextprotocol.io) server. Connect it to your AI assistant and ask in plain language: *"Send a thank-you card to Anna Kowalska at ul. Marszałkowska 10, Warszawa."*

| Setting | Value |
| - | - |
| Server URL | `https://paperjoy.co/mcp` |
| Transport | Streamable HTTP |
| Authentication | OAuth, through your browser |
| Server version | 1.2.0 |

> [!WARNING]
>
> The MCP server always works in **live mode**, even if test mode is on in your browser. By default your assistant saves postcards as free [drafts](https://docs.paperjoy.co/en/postcards/drafts.md), so nothing is sent until you or your assistant submits one. Submitting a draft uses one credit.

## Connect your assistant

You don't need an API key. The first time your assistant connects, a browser window asks you to sign in to Paperjoy and approve access.

> [tab] Claude
>
> In Claude (web or desktop app):
>
> 1. Open **Settings → Connectors** and choose **Add custom connector**.
> 2. Name it `Paperjoy` and paste `https://paperjoy.co/mcp` as the URL.
> 3. Click **Add**, then **Connect**, and approve access in the window that opens.
>
> On Team and Enterprise plans, an Owner may need to add the connector first in the organization's connector settings.
>
> > [!NOTE]
> >
> > Don't add Paperjoy to `claude_desktop_config.json`. That file is for local servers; remote servers like Paperjoy are custom connectors.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http --scope user paperjoy https://paperjoy.co/mcp
> ```
>
> Then run `/mcp` inside Claude Code, select **paperjoy**, and authenticate in the browser. Use `--scope project` instead to share the server with your team through the project's `.mcp.json`.

> [tab] Codex
>
> ```bash theme={null}
> codex mcp add paperjoy --url https://paperjoy.co/mcp
> codex mcp login paperjoy
> ```
>
> Your browser opens to sign in and approve access. Codex CLI, the Codex IDE extension, and the ChatGPT desktop app on the same machine share this configuration.

> [tab] Cursor
>
> Add the server to `~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` for one project:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "paperjoy": {
>       "url": "https://paperjoy.co/mcp"
>     }
>   }
> }
> ```
>
> Open Cursor's MCP settings, select Paperjoy, and complete the sign-in. With Cursor Agent in the terminal, run `cursor-agent mcp login paperjoy`.

> [tab] Other clients
>
> Add a remote **Streamable HTTP** server named `paperjoy` with the URL `https://paperjoy.co/mcp`. Many clients use this shape:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "paperjoy": {
>       "type": "http",
>       "url": "https://paperjoy.co/mcp"
>     }
>   }
> }
> ```
>
> Some clients call the type `streamable-http` or infer it from the URL. The client must support OAuth 2.1 with the authorization code flow, PKCE, and browser sign-in. Paperjoy registers the client automatically, so you don't need a client ID. The device authorization flow (device codes) isn't supported.

![The Paperjoy authorization screen titled Autoryzuj Claude, showing the signed-in account and the MCP server permission, with Anuluj and Autoryzuj buttons.](https://mintcdn.com/paperjoy/F1MJj4Vyrx0MCZIR/images/app/mcp-consent.webp?fit=max\&auto=format\&n=F1MJj4Vyrx0MCZIR\&q=85\&s=f3a8cf0a3266279937564759c60b4f14)

The approval screen lists the account and the permissions your assistant receives.

Click **Autoryzuj** (Authorize) to connect, or **Anuluj** (Cancel) to refuse.

## Available tools

| Tool | What it does |
| - | - |
| `get-account-status` | Returns your account and `available_credit_balance`. |
| `create-postcard-tool` | Saves a free [draft](https://docs.paperjoy.co/en/postcards/drafts.md) by default. Every field is optional. Set `draft` to `false` to order it right away, which uses one credit and needs the `mcp:submit` permission. Optional `idempotency_key`: a retry with the same key returns the first postcard instead of creating a second one. |
| `update-draft-tool` | Changes a draft. Only the fields you send are changed; `null` clears a field. Submitted postcards can't be changed. |
| `preview-postcard-tool` | Renders a postcard by ID: a PNG of the handwritten card, a PNG of the addressed envelope once the address, recipient, and font are set, and a summary with `ready_to_submit`, `issues` (missing or invalid fields), `overflowing_fields` (text that doesn't fit the card), and `envelope_issue`. For drafts it also returns `review_url`, a link that opens the draft in the Paperjoy editor. |
| `submit-postcard-tool` | Orders a draft by ID and uses one credit. Needs the `mcp:submit` permission. An incomplete draft stays a draft and the error lists what to fix. Optional `idempotency_key`, so a retry is charged only once. |
| `delete-draft-tool` | Permanently deletes a draft by ID. Submitted postcards can't be deleted. |
| `list-postcards-tool` | Lists your postcards, newest first, including drafts. Filters: `company_name`, `last_name` (partial matches), `status` (for example `draft`), `limit` (1–100, default 25). |
| `get-postcard-tool` | Returns one postcard by ID, such as `pc_MXP7a4Ni0c`. |
| `list-signatures-tool` | Lists your active [custom signatures](https://docs.paperjoy.co/en/postcards/custom-signatures.md). Pass an ID as `signature_id` when creating a postcard. |

## Things to ask

* *"How many Paperjoy credits do I have left?"*
* *"Draft a thank-you card for Studio Forma in Poznań and show me a preview."*
* *"Send the same birthday card to these three people, using my custom signature."*
* *"Has the card to Katarzyna Zielińska been sent yet?"*

## Troubleshooting

* **No browser window opened.** Run the client's login command again, or click **Connect** or **Authenticate** in its MCP settings.
* **Paperjoy shows up but has no tools.** Check that the URL is exactly `https://paperjoy.co/mcp`, then restart or refresh the client.
* **An API key was rejected.** That's expected. The MCP server only accepts the OAuth sign-in.
* **The client asks for a device code.** Use a client that supports the authorization code flow with PKCE.

## Limits

* 120 MCP requests per minute.
* Ordering postcards (submitting a draft, or creating one with `draft: false`) shares the daily limit of 100 with the API and the editor. Drafts don't count.
* Up to 100 open drafts at a time.
* Previews share the limit of 30 per minute.

Every tool response for a draft includes `review_url`, so your assistant can hand you a link to review and send it yourself in the editor.

## Sending needs a separate permission

Paperjoy asks for two permissions when you connect, and the approval screen lists both:

| Permission | What it allows |
| - | - |
| `mcp:use` | Read your account, signatures, and postcards, and create, preview, and edit drafts. |
| `mcp:submit` | Send postcards for you, which uses credits. |

Without `mcp:submit`, your assistant can prepare drafts but can't send them. `submit-postcard-tool` and `create-postcard-tool` with `draft: false` then return an error asking you to send the draft from the dashboard, or to reconnect and approve `mcp:submit`.

Connections made before this permission existed only have `mcp:use`. Reconnect the server and approve access again to let your assistant send postcards.

The assistant only sees postcards and signatures from your own account.

> [!NOTE]
>
> API keys (`pj_live_`, `pj_test_`) don't work with the MCP server. Use them with the [API](https://docs.paperjoy.co/en/getting-started/quickstart.md) and [Zapier](https://docs.paperjoy.co/en/integrations/zapier.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.