paymcp-subscription-demo

PayMCP/paymcp-subscription-demo

3.2

If you are the rightful owner of paymcp-subscription-demo and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This document provides a structured summary of a Model Context Protocol (MCP) server that integrates with PayMCP and Stripe for subscription management, using OAuth/OIDC for authentication.

Tools
1
Resources
0
Prompts
0

PayMCP Subscription Demo

Sample MCP server that gates tools behind active subscriptions using PayMCP with Stripe as the billing provider and OAuth/OIDC for authentication.

  • Protects MCP tools with bearer tokens from Auth0, generic OIDC, or Keycloak
  • Enforces paid access to tools (demo add tool) via Stripe subscriptions
  • Exposes OAuth discovery metadata at the root for MCP clients

Quick start

  1. Copy .env.example to .env and fill in your auth + Stripe values.
  2. Install deps: yarn install.
  3. Run the server: yarn dev (default: http://localhost:3000).
  4. Connect with an MCP client, authenticate, and call the add tool—access requires an active Stripe subscription matching STRIPE_SUBSCRIPTION_ID.

Environment

  • HOST / PORT: MCP server host/port (defaults: localhost:3000).
  • OIDC_ISSUER: Issuer URL for Auth0 / generic OIDC (leave empty if using Keycloak-style config).
  • AUTH_HOST, AUTH_PORT, AUTH_REALM: Keycloak location if not using OIDC_ISSUER.
  • OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET: OAuth client credentials.
  • STRIPE_SECRET_KEY: Stripe secret key for PayMCP.
  • STRIPE_SUBSCRIPTION_ID: Stripe price ID that represents the required plan.

Auth provider setup

Auth0
  1. In Auth0 Dashboard: Applications → APIs → Create API. Set Identifier to your MCP server hostname (e.g., http://localhost:3000/).
  2. Create a Client Application and copy domain, client ID, client secret into .env (OIDC_ISSUER, OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET).
  3. Authentication → Database: create Username-Password-Authentication connection.
  4. Username-Password-Authentication connection → Promote that connection to Domain Level.
  5. Settings → Advanced Settings: enable Dynamic Client Registration (DCR) and Resource Parameter Compatibility Profile.
Keycloak

Use the official MCP authorization walkthrough: https://modelcontextprotocol.io/docs/tutorials/security/authorization. Then set AUTH_HOST, AUTH_PORT, AUTH_REALM, OAUTH_CLIENT_ID, and OAUTH_CLIENT_SECRET in .env (leave OIDC_ISSUER empty).

Stripe setup

  1. Create a product in the Stripe dashboard and a recurring price.
  2. Set STRIPE_SUBSCRIPTION_ID to that price ID.
  3. Set STRIPE_SECRET_KEY to your Stripe secret key.
    PayMCP will use these to check subscription status and to generate checkout/manage links exposed to the MCP client.

Running

  • Dev server: yarn dev
  • Build: yarn build
  • Start built server: yarn start

The MCP server runs over HTTP with OAuth-protected endpoints (/ for session requests). OAuth metadata is published automatically for clients via mcpAuthMetadataRouter.

How access control works

  • OAuth bearer tokens are verified against your provider and must target the MCP resource (HOST:PORT).
  • The demo add tool declares a subscription requirement via _meta.subscription.plan = STRIPE_SUBSCRIPTION_ID; PayMCP enforces it.
  • PayMCP adds three helper methods to let users obtain a checkout link and manage their subscription directly in chat.

Troubleshooting

  • 401 or audience errors: ensure the API Identifier (Auth0) or resource indicator matches http://HOST:PORT.
  • Invalid JWT shape: confirm your provider issues JWT access tokens (not opaque tokens).
  • Stripe errors: double-check STRIPE_SECRET_KEY and that STRIPE_SUBSCRIPTION_ID exists and is active.