Paperjoy MCP server for Claude and AI assistants

Paperjoy runs a remote MCP 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

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, 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.

Claude
Claude Code
Codex
Cursor
Other clients

In Claude (web or desktop app):

Open Settings → Connectors and choose Add custom connector.
Name it Paperjoy and paste https://paperjoy.co/mcp as the URL.
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.

Don’t add Paperjoy to claude_desktop_config.json. That file is for local servers; remote servers like Paperjoy are custom connectors.

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.

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.

Add the server to ~/.cursor/mcp.json for all projects, or .cursor/mcp.json for one project:

{
  "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.

Add a remote Streamable HTTP server named paperjoy with the URL https://paperjoy.co/mcp. Many clients use this shape:

{
  "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. — 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 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. 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.

API keys (pj_live_, pj_test_) don’t work with the MCP server. Use them with the API and Zapier.

Get started

Ways to send

Postcards

Account

API reference

Paperjoy MCP server for Claude and AI assistants

Connect your assistant

Available tools

Things to ask

Troubleshooting

Limits

Sending needs a separate permission

​Connect your assistant

​Available tools

​Things to ask

​Troubleshooting

​Limits

​Sending needs a separate permission

Connect your assistant

Available tools

Things to ask

Troubleshooting

Limits

Sending needs a separate permission