Crosspay MCP Server

The Crosspay MCP server exposes Crosspay as Model Context Protocol tools. AI agents like Claude Desktop, Cursor, Claude Code, and any MCP client can check customer entitlements, manage subscriptions, and connect payment stores using natural language.

Capabilities

The server provides two groups of tools, each authenticated with a different API key sent in the api-key header. Set whichever keys you need.

Backend tools

These tools require a private key (CROSSPAY_API_KEY).

Tool	Description
crosspay_check_customer_entitlements	Check whether a customer has active premium access on any store. This is the single source of truth for entitlement status.
crosspay_list_customers	List customers with cursor-based pagination.
crosspay_cancel_stripe_subscription	Cancel a customer’s Stripe subscription.
crosspay_cancel_gocardless_subscription	Cancel a customer’s GoCardless subscription.

Management tools

These tools require a management key (CROSSPAY_MANAGEMENT_API_KEY).

Tool	Description
crosspay_list_apps	List all apps in your organization.
crosspay_create_app	Create a new app.
crosspay_list_entitlements	List entitlements for an app.
crosspay_create_entitlement	Create a new entitlement.
crosspay_list_products	List products linked to an entitlement.
crosspay_get_store_config	View which stores are connected to an app. Secrets are not returned.
crosspay_store_connection_guide	Get step-by-step instructions for connecting a store, including dashboard location, webhook URLs, and which fields are secret.

Note

Store secrets are entered only in the Crosspay dashboard. The MCP server has no tool that accepts store credentials, and the API rejects store-config writes from API keys. The server guides you through the process, but you paste secrets directly in the dashboard UI.

Get your API keys

In the dashboard, navigate to Crosspay Dashboard > API Keys > Create New Key and choose the key type you need:

• Secret (private): For backend tools. Keep this server-side only.
• Management: For management and store-config tools. This key acts on your behalf with your org role. Keep it server-side.

Publishable and public keys are intended for client SDKs and are rejected by the MCP server.

Configure your client

Add the following configuration to your MCP client. This works with Claude Desktop, Cursor, Claude Code, and other stdio-based clients.

{
  "mcpServers": {
    "crosspay": {
      "command": "npx",
      "args": ["-y", "@crosspay/mcp-server"],
      "env": {
        "CROSSPAY_API_KEY": "your_private_key",
        "CROSSPAY_MANAGEMENT_API_KEY": "your_management_key",
        "CROSSPAY_BASE_URL": "https://api.crosspay.dev"
      }
    }
  }
}

You do not need to set both keys. Set only the keys for the tools you plan to use. Each tool returns a clear error if its required key is missing.

Example prompts

Here are some things you can ask your AI agent once the MCP server is configured:

• “Does alice@example.com still have premium access?”
• “List my apps, then show which stores my Acme app has connected.”
• “How do I connect Stripe to my Acme app?” The agent returns a setup guide. You enter the secrets in the dashboard. See the store onboarding skill for details.
• “Cancel bob@example.com’s Stripe subscription for the pro entitlement.”

Security

• Treat the management key like a password. Store it in a secrets vault or environment variable. Never commit it to client code.
• Store-config tools forward credentials (Stripe keys, GoCardless tokens, service-account JSON) to Crosspay and never echo them back. Crosspay validates every credential live at connect time.
• You can revoke keys at any time from the dashboard.

Self-hosted

Point CROSSPAY_BASE_URL at your own instance (for example, http://localhost:8080). Set TRANSPORT=http to run a remote streamable-HTTP server instead of stdio.

For source code and full documentation, see the crosspay-mcp-server package.