paperplane-mcp

An MCP connector for Paperplane — the inbox for the events your machines send you.

It lets an AI tool page you on your phone when a long job finishes or needs a decision, read back what fired, acknowledge or resolve an alert, and file a follow-up ticket. One long-lived credential, no per-channel keys.

Setup

1. Create a token

In the Paperplane app: Settings → Developer tokens → Create token. The secret is shown once — copy it then. It looks like pplt_ followed by 64 hex characters.

2. Point a client at it

Claude Code — .mcp.json in your project, or ~/.claude.json for every project:

{
  "mcpServers": {
    "paperplane": {
      "command": "npx",
      "args": ["-y", "paperplane-mcp"],
      "env": {
        "PAPERPLANE_TOKEN": "pplt_...",
        "PAPERPLANE_DEFAULT_CHANNEL": "Builds"
      }
    }
  }
}

Claude Desktop uses the same block inside claude_desktop_config.json.

The server checks the token at startup, so a revoked one fails fast with a message on stderr rather than surfacing mid-conversation.

Related MCP server: confluence-mcp-server

Tools

Making something an alert

An event becomes an alert — badged, counted under "Needs attention", requiring acknowledgement — when nature is one of error, failure, failed, critical, pending, or priority is one of high, crit, critical, urgent. Anything else is an ordinary message.

Action buttons

callback attaches buttons to the notification:

{
  "title": "Deploy failed",
  "message": "api-service · main @ abc123",
  "nature": "error",
  "callback": [{ "label": "Re-run pipeline", "webhook": "https://ci.example.com/hooks/rerun" }]
}

The phone fires the webhook when the button is pressed — the connector never calls it.

Scopes

A token carries scopes; the connector uses events:write, channels:read, messages:read, messages:write, tickets:read, and tickets:write. Tokens minted from the app carry all of them. Mint a narrower one via the API if you want a send-only credential:

curl -X POST "$PAPERPLANE_API_BASE_URL/tokens" \
  -H "authorization: Bearer $SESSION_JWT" -H 'content-type: application/json' \
  -d '{"name":"CI notifier","scopes":["events:write"]}'

Channel administration, membership, retention, and token management are session-only and stay out of reach of any token.

Development

npm install
npm run build
npm run inspect   # builds, then opens the MCP Inspector

Point it at a local backend with PAPERPLANE_API_BASE_URL=http://localhost:8787.

Tool handlers in src/tools/ take parsed arguments and return plain values — they know nothing about MCP framing, so mounting them on a remote HTTP transport later is additive rather than a rewrite.