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:
```bash
STRIPE_SECRET_KEY=sk_test_...  # or sk_live_... for production
```

### 2. Run Stripe MCP Server

```bash
# 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:**
```bash
cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

**Windows:**
```bash
copy claude_desktop_config.json %APPDATA%\Claude\claude_desktop_config.json
```

**Linux:**
```bash
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:
```bash
npx @stripe/mcp --tools=customers.create,customers.read,products.create --api-key=$STRIPE_SECRET_KEY
```

## Stripe Connect Account

For Stripe Connect operations:
```bash
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:
```bash
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](https://docs.stripe.com/building-with-llms).