# Bridge MCP Server - Setup Guide
## Overview
This guide walks you through setting up the Bridge MCP Server with authentication, HubSpot Payments integration, and deployment to Google Cloud Run.
---
## Prerequisites
1. **Supabase Account** - For database (customer/token storage)
2. **HubSpot Account** - For payment processing and webhooks
3. **Google Cloud Account** - For hosting on Cloud Run
4. **Node.js 18+** - For local development
---
## Step 1: Supabase Setup
### 1.1 Create the Database Schema
1. Go to your Supabase project: https://app.supabase.com
2. Navigate to SQL Editor
3. Run the SQL from `supabase-schema.sql` (in this repo)
4. This creates:
- `customers` table - stores customer info and access tokens
- `webhook_logs` table - logs all webhook events for debugging
### 1.2 Get Your Credentials
1. Go to Project Settings → API
2. Copy:
- **Project URL** (e.g., `https://xxxxx.supabase.co`)
- **Anon/Public Key** (starts with `eyJhbGci...`)
3. Save these for the next step
---
## Step 2: Environment Variables
### 2.1 Local Development
1. Copy `.env.example` to `.env`:
```bash
cp .env.example .env
```
2. Update `.env` with your credentials:
```env
PORT=8080
SUPABASE_URL=https://wfjkxurymrbjulnfvkzo.supabase.co
SUPABASE_KEY=your_supabase_key_here
HUBSPOT_WEBHOOK_SECRET=your_webhook_secret_here
```
### 2.2 Cloud Run Deployment
When deploying to Cloud Run, set these environment variables:
```bash
gcloud run deploy bridge-mcp \
--set-env-vars SUPABASE_URL=https://wfjkxurymrbjulnfvkzo.supabase.co \
--set-env-vars SUPABASE_KEY=your_key_here \
--set-env-vars HUBSPOT_WEBHOOK_SECRET=your_secret_here
```
Or use the `deploy.sh` script (update it with your env vars).
---
## Step 3: HubSpot Payment Integration
### 3.1 Create a Payment Product in HubSpot
1. Go to **Commerce** → **Products**
2. Create a new product:
- **Name**: Bridge MCP Subscription
- **Price**: $29/month
- **Recurring**: Yes (monthly)
3. Create a payment link or embed form on your sales page
### 3.2 Set Up HubSpot Webhooks
1. Go to **Settings** → **Integrations** → **Private Apps**
2. Create a new Private App or use existing
3. Go to **Workflows** and create a webhook workflow:
- **Trigger**: Deal created (or payment succeeded)
- **Action**: Send webhook to `https://YOUR_CLOUD_RUN_URL/webhooks/hubspot`
4. Configure webhook settings:
- **Method**: POST
- **URL**: `https://bridge-mcp-xxxxx.run.app/webhooks/hubspot`
- **Include**: Contact email, Deal properties
- **Webhook Secret**: Generate one and save it to your `.env`
### 3.3 Webhook Events Handled
The Bridge server handles these events:
- `deal.creation` → Creates customer, generates token
- `payment.succeeded` → Activates customer
- `payment.failed` → Sets status to `past_due`
- `deal.deletion` / `subscription.cancelled` → Sets status to `cancelled`
---
## Step 4: Install Dependencies
```bash
npm install
```
This installs:
- `@modelcontextprotocol/sdk` - MCP server framework
- `@supabase/supabase-js` - Supabase client
- `express` - Web server
- `zod` - Schema validation
---
## Step 5: Local Testing
### 5.1 Build and Run
```bash
npm run build
npm start
```
Server runs at: `http://localhost:8080`
### 5.2 Test Endpoints
**Health Check:**
```bash
curl http://localhost:8080/health
```
**Create a Test Customer (Manually):**
Use Supabase SQL Editor:
```sql
INSERT INTO customers (email, access_token, subscription_status)
VALUES ('test@example.com', 'bridge_test123', 'active');
```
**Test MCP Endpoint (with auth):**
```bash
curl -X POST http://localhost:8080/mcp \
-H "Authorization: Bearer bridge_test123" \
-H "Content-Type: application/json" \
-d '{"method":"tools/list"}'
```
**Test HubSpot Webhook:**
```bash
curl -X POST http://localhost:8080/webhooks/hubspot \
-H "Content-Type: application/json" \
-d '{
"subscriptionType": "deal.creation",
"objectId": "12345",
"properties": {
"email": "tim@example.com",
"hs_object_id": "12345"
}
}'
```
Check Supabase to see if the customer was created!
---
## Step 6: Deploy to Google Cloud Run
### 6.1 Using the Deploy Script
```bash
chmod +x deploy.sh
./deploy.sh
```
### 6.2 Manual Deployment
```bash
# Set your project
gcloud config set project YOUR_PROJECT_ID
# Build container
gcloud builds submit --tag gcr.io/YOUR_PROJECT_ID/bridge-mcp
# Deploy with env vars
gcloud run deploy bridge-mcp \
--image gcr.io/YOUR_PROJECT_ID/bridge-mcp \
--platform managed \
--region us-central1 \
--allow-unauthenticated \
--memory 512Mi \
--set-env-vars SUPABASE_URL=https://wfjkxurymrbjulnfvkzo.supabase.co \
--set-env-vars SUPABASE_KEY=your_key_here \
--set-env-vars HUBSPOT_WEBHOOK_SECRET=your_secret_here
```
### 6.3 Get Your Server URL
After deployment, you'll get a URL like:
```
https://bridge-mcp-xxxxx-uc.a.run.app
```
Update your HubSpot webhook to point to this URL!
---
## Step 7: Customer Onboarding Flow
### 7.1 When a Customer Subscribes
1. Customer pays via HubSpot payment link ($29/month)
2. HubSpot sends webhook to `/webhooks/hubspot`
3. Bridge server:
- Creates customer record in Supabase
- Generates unique access token
- Returns token in webhook response
4. You send customer their access token via email
### 7.2 Email Template for Customers
```
Subject: Welcome to Bridge MCP! 🌉
Hi [Name],
Thanks for subscribing to Bridge MCP!
Here's your access token:
bridge_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
To connect Claude to Bridge:
1. Open Claude settings → Integrations → MCP Servers
2. Add new server: https://bridge-mcp-xxxxx.run.app/mcp
3. Add header: Authorization: Bearer [your_token]
You're all set! Try asking Claude:
- "Get my ClickUp task templates"
- "Load the transcript-to-tasks skill"
Questions? Reply to this email!
— Amara
AI Foundations
```
---
## Step 8: Monitoring & Debugging
### 8.1 View Webhook Logs
Check Supabase `webhook_logs` table:
```sql
SELECT * FROM webhook_logs ORDER BY created_at DESC LIMIT 10;
```
### 8.2 View Customers
```sql
SELECT email, subscription_status, created_at FROM customers;
```
### 8.3 Regenerate a Token
If a customer loses their token:
```sql
UPDATE customers
SET access_token = 'bridge_' || encode(gen_random_bytes(32), 'hex')
WHERE email = 'customer@example.com'
RETURNING access_token;
```
### 8.4 Cloud Run Logs
```bash
gcloud run logs read bridge-mcp --limit 50
```
---
## Troubleshooting
### "Missing SUPABASE_URL or SUPABASE_KEY"
- Check environment variables are set in Cloud Run
- Verify `.env` file exists locally
### "Unauthorized" on MCP requests
- Verify token format: `bridge_` followed by 64 hex characters
- Check customer exists in Supabase
- Check `subscription_status` is `active` or `trialing`
### HubSpot webhook not creating customers
- Check `webhook_logs` table for errors
- Verify webhook URL is correct
- Test webhook signature (set `HUBSPOT_WEBHOOK_SECRET`)
### Customer has token but MCP returns 401
- Check token matches exactly (no spaces)
- Verify subscription_status in database
---
## Security Notes
1. **Never commit `.env`** - Already in `.gitignore`
2. **Use HubSpot webhook signatures** - Set `HUBSPOT_WEBHOOK_SECRET`
3. **Tokens are permanent** - Only revoked when subscription cancelled
4. **Supabase RLS** - Consider enabling Row Level Security for extra protection
5. **Rate limiting** - Consider adding rate limits in production
---
## Next Steps
- [ ] Run Supabase schema migration
- [ ] Configure HubSpot payment product
- [ ] Set up HubSpot webhooks
- [ ] Deploy to Cloud Run
- [ ] Test end-to-end with a test customer
- [ ] Create customer email template
- [ ] Monitor first real customer onboarding
---
**Questions?** Check the PROJECT_CONTEXT.md or ask Amara!
Built by AI Foundations by Amara
*"I prompt like shit. But I get glorious results."*
