vibn-frontend/MCP_API_KEYS_GUIDE.md

# 🔑 MCP API Keys for ChatGPT Integration

## ✅ Non-Expiring API Keys - Complete!

I've built a complete system for **non-expiring API keys** that users can generate directly in the Vibn UI to connect ChatGPT.

---

## 🎯 How It Works

### **1. User Visits Connections Page**
**URL:** `https://vibnai.com/your-workspace/connections`

### **2. Generate API Key**
- Click **"Generate MCP API Key"** button
- System creates a unique, long-lived key: `vibn_mcp_abc123...`
- Key is stored in Firestore (`mcpKeys` collection)
- **Key never expires** until explicitly revoked

### **3. Copy Settings to ChatGPT**
- Click **"Copy All Settings"** button
- Paste into ChatGPT's "New Connector" form
- Done! ChatGPT can now access Vibn data

---

## 🏗️ What I Built

### **1. API Key Generation Endpoint**
**File:** `app/api/mcp/generate-key/route.ts`

```typescript
POST /api/mcp/generate-key
- Generates: vibn_mcp_{64-character-hex}
- Stores in Firestore with userId
- Returns existing key if one already exists
```

```typescript
DELETE /api/mcp/generate-key
- Revokes user's MCP API key
- Removes from Firestore
- Forces ChatGPT to disconnect
```

### **2. Updated MCP API to Accept API Keys**
**File:** `app/api/mcp/route.ts`

The MCP endpoint now accepts **two types** of authentication:

**Option A: MCP API Key** (for ChatGPT)
```bash
Authorization: Bearer vibn_mcp_abc123...
```

**Option B: Firebase ID Token** (for direct user access)
```bash
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
```

### **3. UI Component for Key Management**
**File:** `components/mcp-connection-card.tsx`

Features:
- ✅ Generate API key button
- ✅ Show/hide key toggle
- ✅ Copy individual settings
- ✅ **Copy all settings** button (one-click setup!)
- ✅ Setup instructions
- ✅ Revoke key with confirmation dialog

### **4. Integrated into Connections Page**
**File:** `app/[workspace]/connections/page.tsx`

The MCP connection card is now live on the Connections page, replacing the old placeholder.

### **5. Firestore Security Rules**
**File:** `firestore.rules`

```javascript
match /mcpKeys/{keyId} {
  // Only server can manage keys via Admin SDK
  // Users can't directly access or modify
  allow read, write: if false;
}
```

**Deployed:** ✅ Rules are live in production

---

## 📋 User Flow (Step-by-Step)

### **From Vibn:**

1. User goes to: `/your-workspace/connections`
2. Scrolls to "ChatGPT Integration (MCP)" card
3. Clicks: **"Generate MCP API Key"**
4. Waits 1-2 seconds
5. Sees:
   - MCP Server URL: `https://vibnai.com/api/mcp`
   - API Key: `vibn_mcp_...` (hidden by default)
6. Clicks: **"Copy All Settings"**
7. Toast: "All settings copied! Paste into ChatGPT"

### **To ChatGPT:**

1. User opens ChatGPT
2. Goes to: **Settings → Personalization → Custom Tools**
3. Clicks: **"Add New Connector"**
4. Pastes settings from clipboard:
   ```
   Name: Vibn
   Description: Access your Vibn coding projects...
   MCP Server URL: https://vibnai.com/api/mcp
   Authentication: Bearer
   API Key: vibn_mcp_abc123...
   ```
5. Checks: **"I understand and want to continue"**
6. Clicks: **"Create"**
7. Done! ✅

### **Test It:**

User asks ChatGPT:
- "Show me my Vibn projects"
- "What are my recent coding sessions?"
- "How much have I spent on AI?"

ChatGPT uses the MCP API key to fetch data and respond!

---

## 🔐 Security Features

### **API Key Format:**
```
vibn_mcp_{64-character-hex-string}
```

**Example:** `vibn_mcp_a1b2c3d4e5f6...` (72 chars total)

### **Storage:**
```javascript
// Firestore: mcpKeys collection
{
  userId: "firebase-user-id",
  key: "vibn_mcp_abc123...",
  type: "mcp",
  createdAt: "2024-11-14T...",
  lastUsed: "2024-11-14T..." // Updated on each use
}
```

### **Authentication Flow:**

```
ChatGPT Request
  ↓
POST /api/mcp
  Authorization: Bearer vibn_mcp_abc123...
  ↓
Check if token starts with "vibn_mcp_"
  ↓
Query Firestore: mcpKeys.where('key', '==', token)
  ↓
Extract userId from key doc
  ↓
Update lastUsed timestamp
  ↓
Process MCP request with userId context
  ↓
Return data to ChatGPT
```

### **Security Rules:**
- ✅ Users can't directly read their key from Firestore
- ✅ Keys are only accessible via Admin SDK (server-side)
- ✅ Keys are scoped to a single user
- ✅ All MCP queries filter by userId
- ✅ Keys can be revoked instantly

---

## 🆚 Comparison: Old vs New

### **Old Way (Manual):**
❌ User needs to run console commands  
❌ Firebase ID token expires every 1 hour  
❌ User must regenerate token constantly  
❌ Poor user experience  

### **New Way (API Keys):**
✅ User clicks a button  
✅ Key never expires  
✅ One-time setup  
✅ Can be revoked anytime  
✅ Great user experience  

---

## 📊 Database Schema

### **mcpKeys Collection:**
```typescript
{
  userId: string;          // Firebase user ID
  key: string;             // vibn_mcp_{hex}
  type: string;            // "mcp"
  createdAt: string;       // ISO timestamp
  lastUsed: string | null; // ISO timestamp or null
}
```

### **Indexes:**
```javascript
// Compound index on 'key' (for fast lookup during auth)
mcpKeys: {
  key: "ascending"
}
```

---

## 🧪 Testing

### **1. Generate Key:**
```bash
# From browser console (when logged in):
const token = await firebase.auth().currentUser.getIdToken();
const response = await fetch('/api/mcp/generate-key', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` }
});
const data = await response.json();
console.log(data.apiKey);
```

### **2. Test API with Key:**
```bash
curl -X POST https://vibnai.com/api/mcp \
  -H "Authorization: Bearer vibn_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "list_resources"}'
```

### **3. Revoke Key:**
```bash
const token = await firebase.auth().currentUser.getIdToken();
await fetch('/api/mcp/generate-key', {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${token}` }
});
```

---

## 🎯 Benefits

### **For Users:**
- ✅ No technical knowledge required
- ✅ One-click copy/paste setup
- ✅ Keys never expire (set and forget)
- ✅ Clear revocation if needed
- ✅ Visual feedback (show/hide key)

### **For ChatGPT:**
- ✅ Stable, long-lived authentication
- ✅ Fast key validation (Firestore lookup)
- ✅ Automatic last-used tracking
- ✅ User-scoped data access

### **For Vibn:**
- ✅ No Firebase ID token management
- ✅ Simple key rotation if needed
- ✅ Usage analytics (lastUsed field)
- ✅ Better security posture

---

## 📝 Files Modified/Created

### **New Files:**
```
app/api/mcp/generate-key/route.ts    ← Key generation/revocation API
components/mcp-connection-card.tsx   ← UI component for key management
MCP_API_KEYS_GUIDE.md                ← This file
```

### **Modified Files:**
```
app/api/mcp/route.ts                 ← Now accepts MCP API keys
app/[workspace]/connections/page.tsx ← Integrated MCP card
firestore.rules                      ← Added mcpKeys rules
```

---

## 🚀 What's Live

✅ **API Key Generation:** `/api/mcp/generate-key`  
✅ **API Key Authentication:** `/api/mcp`  
✅ **UI for Key Management:** `/your-workspace/connections`  
✅ **Firestore Rules:** Deployed to production  
✅ **Security:** Keys are server-side only  

---

## 🎉 Result

**Users can now:**
1. Generate a non-expiring API key in 1 click
2. Copy all settings in 1 click
3. Paste into ChatGPT's connector form
4. Connect ChatGPT to their Vibn data
5. Never worry about token expiration

**No console commands. No manual token refresh. Just works!** ✨

---

## 🔮 Future Enhancements

Potential additions:
- [ ] Multiple MCP keys per user (for different AI assistants)
- [ ] Key usage analytics dashboard
- [ ] Automatic key rotation (optional)
- [ ] Scoped keys (read-only vs full access)
- [ ] Key expiration dates (optional)

---

**Built and ready to use!** 🚀

Visit: `https://vibnai.com/your-workspace/connections` to try it now!