mcp-boilerplate

While the boilerplate includes built-in Stripe integration that verifies payments automatically, you can optionally set up webhooks to handle advanced logic like usage-based billing, custom subscription workflows, or customer dashboards.

To configure webhooks:

1. In your Stripe Dashboard, navigate to Developers > Webhooks and click Add endpoint.
2. Set the endpoint URL based on your environment:
   • Local development: http://localhost:8787/webhooks/stripe
   • Production: https://your-worker-name.your-account.workers.dev/webhooks/stripe
3. Select relevant events (e.g., checkout.session.completed, invoice.payment_succeeded, customer.subscription.updated).
4. Copy the Signing secret and add it to your environment configuration.

# Local development (.dev.vars)
STRIPE_WEBHOOK_SECRET="whsec_your-webhook-secret-here"

# Production (using Wrangler)
npx wrangler secret put STRIPE_WEBHOOK_SECRET

Use this option to charge a single fee for access to a tool.

Stripe Setup:

1. Create a Product in Stripe.
2. Add a Price with the "One time" model.
3. Note the price_xxxxxxxxxxxxxx ID.

Implementation:

1. Create a file in src/tools/.
2. Use agent.paidTool.
3. In the configuration object, set checkout.mode to 'payment'.
4. Register the tool in src/index.ts passing STRIPE_ONE_TIME_PRICE_ID and BASE_URL.
5. Add STRIPE_ONE_TIME_PRICE_ID to your .dev.vars or Cloudflare secrets.

Environment Variable Setup:

• Local: Add to .dev.vars
• Production: npx wrangler secret put STRIPE_ONE_TIME_PRICE_ID

import { z } from "zod";
import { experimental_PaidMcpAgent as PaidMcpAgent } from "@stripe/agent-toolkit/cloudflare";
import { REUSABLE_PAYMENT_REASON } from "../helpers/constants";

export function myOnetimeTool(
  agent: PaidMcpAgent<Env, any, any>,
  env?: { STRIPE_ONE_TIME_PRICE_ID: string; BASE_URL: string }
) {
  const priceId = env?.STRIPE_ONE_TIME_PRICE_ID || null;
  const baseUrl = env?.BASE_URL || null;

  if (!priceId || !baseUrl) {
    throw new Error("Stripe One-Time Price ID and Base URL must be provided for this tool");
  }

  agent.paidTool(
    "my_onetime_tool_name",
    {
      input1: z.string(),
    },
    async ({ input1 }: { input1: string }) => ({
      content: [
        { type: "text", text: `You processed: ${input1}` },
      ],
    }),
    {
      checkout: {
        success_url: `${baseUrl}/payment/success`,
        line_items: [
          {
            price: priceId,
            quantity: 1,
          },
        ],
        mode: 'payment',
      },
      paymentReason: "Enter a clear reason for this one-time charge.",
    }
  );
}

To create a free tool that users can access without payment, follow these steps:

1. Create a new file in src/tools/ (e.g., myTool.ts).
2. Implement the tool using the agent.server.tool method. You must define the tool name, a description, and input parameters using zod schemas.
3. Export the tool function.
4. Add the export to src/tools/index.ts using export * from './myTool';.
5. Register the tool in src/index.ts inside the init() method by calling tools.myTool(this);.

import { z } from "zod";
import { experimental_PaidMcpAgent as PaidMcpAgent } from "@stripe/agent-toolkit/cloudflare";

export function myTool(agent: PaidMcpAgent<Env, any, any>) {
  const server = agent.server;
  // @ts-ignore
  server.tool(
    "my_tool_name",                      // The tool name
    "This tool does something cool.",    // Description of what your tool does
    {
      input1: z.string(),                // Parameter definitions using Zod
      input2: z.number()
    },
    async ({ input1, input2 }: { input1: string; input2: number }) => ({
      content: [{ type: "text", text: `You provided: ${input1} and ${input2}` }],
    })
  );
}

Use this option to charge users based on usage (e.g., per unit used).

Stripe Setup:

1. Create a Product in Stripe.
2. Add a Price and check "Usage is metered" under Price options.
3. Define a meter in Stripe and note the event name (e.g., metered_add_usage).

Implementation:

1. Create a file in src/tools/.
2. Use agent.paidTool.
3. In the configuration object, set checkout.mode to 'subscription'.
4. Crucially, provide the meterEvent string that matches your Stripe meter setup.
5. Register the tool in src/index.ts passing STRIPE_METERED_PRICE_ID and BASE_URL.

import { z } from "zod";
import { experimental_PaidMcpAgent as PaidMcpAgent } from "@stripe/agent-toolkit/cloudflare";
import { METERED_TOOL_PAYMENT_REASON } from "../helpers/constants";

export function myMeteredTool(
  agent: PaidMcpAgent<Env, any, any>,
  env?: { STRIPE_METERED_PRICE_ID: string; BASE_URL: string }
) {
  const priceId = env?.STRIPE_METERED_PRICE_ID || null;
  const baseUrl = env?.BASE_URL || null;

  if (!priceId || !baseUrl) {
    throw new Error("Stripe Metered Price ID and Base URL must be provided for metered tools");
  }

  agent.paidTool(
    "my_metered_tool_name",
    {
      a: z.number(),
      b: z.number(),
    },
    async ({ a, b }: { a: number; b: number }) => {
      const result = a + b;
      return {
        content: [{ type: "text", text: String(result) }],
      };
    },
    {
      checkout: {
        success_url: `${baseUrl}/payment/success`,
        line_items: [
          {
            price: priceId,
          },
        ],
        mode: 'subscription',
      },
      paymentReason: "METER INFO: Details about your metered usage. " + METERED_TOOL_PAYMENT_REASON,
      meterEvent: "your_meter_event_name_from_stripe",
    }
  );
}

Use this option to charge users a recurring fee (e.g., monthly) for access to a tool.

Stripe Setup:

1. Create a Product in the Stripe Dashboard.
2. Add a Price with the "Recurring" model.
3. Note the price_xxxxxxxxxxxxxx ID.

Implementation:

1. Create a file in src/tools/.
2. Use agent.paidTool instead of server.tool.
3. Pass a configuration object containing priceId, successUrl, and paymentReason.
4. Register the tool in src/index.ts passing the required environment variables (STRIPE_SUBSCRIPTION_PRICE_ID and BASE_URL).

import { z } from "zod";
import { experimental_PaidMcpAgent as PaidMcpAgent } from "@stripe/agent-toolkit/cloudflare";
import { REUSABLE_PAYMENT_REASON } from "../helpers/constants";

export function mySubscriptionTool(
  agent: PaidMcpAgent<Env, any, any>,
  env?: { STRIPE_SUBSCRIPTION_PRICE_ID: string; BASE_URL: string }
) {
  const priceId = env?.STRIPE_SUBSCRIPTION_PRICE_ID || null;
  const baseUrl = env?.BASE_URL || null;

  if (!priceId || !baseUrl) {
    throw new Error("Stripe Price ID and Base URL must be provided for paid tools");
  }

  agent.paidTool(
    "my_subscription_tool_name",
    {
      input1: z.string(),
      input2: z.number(),
    },
    async ({ input1, input2 }: { input1: string; input2: number }) => ({
      content: [
        { type: "text", text: `You provided: ${input1} and ${input2}` },
      ],
    }),
    {
      priceId,
      successUrl: `${baseUrl}/payment/success`,
      paymentReason: REUSABLE_PAYMENT_REASON,
    }
  );
}

The server uses a standard Cloudflare Workers fetch handler to route incoming requests. The routing logic handles:

• Static Pages: The root path (/) and /payment/success serve HTML pages.
• Webhooks: The /webhooks/stripe path is delegated to the stripeWebhookHandler.
• OAuth/MCP Traffic: All other routes are handled by an OAuthProvider instance, which manages authentication and the MCP SSE (Server-Sent Events) connection.

The OAuthProvider is configured with specific endpoints for authorization, tokens, and client registration, and it uses a defaultHandler (like GoogleHandler) to manage the authentication flow.

const oauthProvider = new OAuthProvider({
	apiRoute: "/sse",
	apiHandler: BoilerplateMCP.mount("/sse") as any,
	defaultHandler: GoogleHandler as any,
	authorizeEndpoint: "/authorize",
	tokenEndpoint: "/token",
	clientRegistrationEndpoint: "/register",
});

export default {
	async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
		// ... routing logic ...
		return oauthProvider.fetch(request, env, ctx);
	};
};