@paperkeyhq/mcp

Model Context Protocol server for Paperkey. Lets Claude Desktop, Cursor, Continue, or any MCP-compatible AI client drive your software-licensing data in natural language.

"show me licenses with more than 5 activations this week"
"revoke the license for [email protected]"
"what's the max-activation count on my Acme product?"

Install

No install needed — npx runs it directly. The first invocation downloads and caches the binary.

Use with Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "paperkey": {
      "command": "npx",
      "args": ["-y", "@paperkeyhq/mcp"],
      "env": {
        "PAPERKEY_API_TOKEN": "eyJ..."
      }
    }
  }
}

Restart Claude Desktop. You'll see "paperkey" in the tools menu.

Use with Cursor

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "paperkey": {
      "command": "npx",
      "args": ["-y", "@paperkeyhq/mcp"],
      "env": {
        "PAPERKEY_API_TOKEN": "eyJ..."
      }
    }
  }
}

Get your API token

The MCP server authenticates as your dashboard user. Grab a JWT from https://app.paperkey.dev/settings (or POST /auth/login). Note that JWTs expire after 7 days; we will ship long-lived personal access tokens (PATs) soon.

Tools exposed

CRUD

| Tool | What it does | |--------------------------------------------|-------------------------------------------------------------| | paperkey_list_products | List products owned by the authenticated user. | | paperkey_get_product | Fetch one product (with API key hints; never the secret). | | paperkey_list_licenses | List licenses, optionally filtered by productId. | | paperkey_get_license | Fetch one license, full activations list and metadata. | | paperkey_find_high_activation_licenses | Surface licenses where activationsCount > threshold. | | paperkey_revoke_license | Revoke a license (reversible via reinstate). | | paperkey_reinstate_license | Restore a revoked license to active. |

Business workflows (added in 0.2.0)

Aggregate server-side so a single tool call replaces N CRUD round-trips. Each returns markdown (primary, paste-ready) plus the structured metrics.

| Tool | What it does | |-----------------------------------|------------------------------------------------------------------------------------| | paperkey_analyze_churn | Churn rate over a window (default 30d, max 180d), per-product + per-cohort breakdown, 4-window baseline comparison so spikes can be flagged. | | paperkey_detect_fraud | License-sharing signals over a window (default 30d, max 90d): fingerprints reused across licenses, fingerprints with many distinct IPs, licenses near their activation cap. | | paperkey_generate_audit_report | Markdown digest of recent activity (default 7d, max 90d): new licenses, activations, revocations, webhook delivery counts, anomalies. Suitable for a customer update email. |

Out of scope, on purpose

The server does not create products, issue new licenses, manage API keys, or modify webhook config — those are dashboard-only operations to prevent an over-eager agent from minting keys. Open an issue on GitHub if you need a tool that's missing.

Configuration

| Env var | Required | Default | |------------------------|----------|-------------------------------| | PAPERKEY_API_TOKEN | yes | — | | PAPERKEY_API_URL | no | https://api.paperkey.dev |

Set PAPERKEY_API_URL=http://localhost:3001 if you're running the API locally.

Build from source

git clone https://github.com/paperkeyhq/mcp
cd mcp
pnpm install
pnpm build
node dist/index.js

Why an MCP server?

Paperkey's "AI-first dashboard" pitch shipped because we use this server ourselves — every "ask the data in English" feature in the product is the same protocol your local IDE speaks. Open standard, no lock-in: bring your own model, bring your own client.