blackcanyontickets/MCP_SETUP.md

Stripe MCP (Model Context Protocol) Setup

This project includes Stripe MCP integration for AI-powered Stripe operations through Claude Code and other AI agents.

What is Stripe MCP?

The Stripe Model Context Protocol (MCP) defines a set of tools that AI agents can use to:

• Interact with the Stripe API
• Search Stripe's knowledge base and documentation
• Automate payment processing tasks
• Manage customers, products, and subscriptions
• Handle refunds and disputes

Quick Start

1. Environment Setup

Ensure your .env file contains your Stripe secret key:

STRIPE_SECRET_KEY=sk_test_...  # or sk_live_... for production

2. Run Stripe MCP Server

# Start the MCP server with all available tools
npm run mcp:stripe

# Or with debugging interface
npm run mcp:stripe:debug

3. Claude Desktop Configuration

Copy the provided claude_desktop_config.json to your Claude Desktop configuration directory:

macOS:

cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

copy claude_desktop_config.json %APPDATA%\Claude\claude_desktop_config.json

Linux:

cp claude_desktop_config.json ~/.config/claude/claude_desktop_config.json

Then update the configuration with your actual Stripe secret key.

Available MCP Tools

The Stripe MCP server provides these tool categories:

Customer Management

• customers.create - Create new customers
• customers.read - Retrieve customer information
• customers.update - Update customer details
• customers.delete - Delete customers

Payment Processing

• payment_intents.create - Create payment intents
• payment_intents.confirm - Confirm payments
• payment_intents.cancel - Cancel payments
• charges.capture - Capture authorized charges

Product & Pricing

• products.create - Create products
• products.read - Retrieve product information
• prices.create - Create pricing tiers
• prices.read - Retrieve pricing information

Subscription Management

• subscriptions.create - Create subscriptions
• subscriptions.read - Retrieve subscription details
• subscriptions.update - Update subscriptions
• subscriptions.cancel - Cancel subscriptions

Financial Operations

• refunds.create - Process refunds
• refunds.read - Retrieve refund information
• disputes.read - Review disputes
• payouts.read - Check payout status

Custom Tool Selection

To use specific tools only:

npx @stripe/mcp --tools=customers.create,customers.read,products.create --api-key=$STRIPE_SECRET_KEY

Stripe Connect Account

For Stripe Connect operations:

npx @stripe/mcp --tools=all --api-key=$STRIPE_SECRET_KEY --stripe-account=CONNECTED_ACCOUNT_ID

Integration with BCT Platform

The MCP integration enhances the Black Canyon Tickets platform by enabling:

1. AI-Powered Customer Support: Automatically handle customer inquiries about payments and refunds
2. Intelligent Analytics: Generate insights from payment and subscription data
3. Automated Dispute Resolution: Handle disputes with AI assistance
4. Smart Subscription Management: Optimize subscription plans based on usage patterns
5. Enhanced Event Management: AI-assisted pricing and capacity optimization

Security Considerations

• Never commit your actual Stripe secret keys to version control
• Use test keys during development
• Ensure proper environment variable configuration
• The MCP server respects all Stripe API security measures
• All operations are logged and auditable

Debugging

Use the MCP Inspector for debugging:

npm run mcp:stripe:debug

This opens a web interface showing:

• Available tools and their schemas
• Real-time request/response logs
• Error messages and stack traces
• Performance metrics

Troubleshooting

Common Issues

1. "Could not connect to MCP server"

   • Verify your Stripe secret key is correct
   • Check that the environment variable is properly set
   • Ensure npx can access @stripe/mcp package

2. "Tool not found"

   • Verify the tool name matches exactly
   • Check if you're using the correct tool subset
   • Ensure the MCP server started successfully

3. "API key invalid"

   • Confirm you're using the correct environment (test vs live)
   • Verify the API key has necessary permissions
   • Check for typos in the environment variable

Logs

MCP server logs are available in the Claude Desktop application logs. Check:

• macOS: ~/Library/Logs/Claude/
• Windows: %LOCALAPPDATA%\Claude\logs\
• Linux: ~/.local/share/claude/logs/

Next Steps

1. Configure Claude Desktop with your Stripe credentials
2. Test the MCP integration with simple customer operations
3. Explore AI-powered payment analytics
4. Implement automated customer support workflows
5. Integrate with the BCT platform's existing Stripe Connect setup

For more information, see the Stripe MCP Documentation.