@chandshantanu/agentbuilder-mcp-server 0.2.0

package/PRODUCTION_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,486 @@
+# AgentBuilder MCP Server - Production Deployment Guide
+
+**Date**: 2026-01-26
+**Current Version**: 0.2.0
+**Target Environment**: Production (Azure AKS)
+
+---
+
+## ⚠️ REQUIRED UPDATES FOR PRODUCTION
+
+### Critical Changes Needed
+
+**Current Configuration:** ❌ Pointing to localhost
+**Required Configuration:** ✅ Point to production API
+
+---
+
+## 🔧 Step-by-Step Production Setup
+
+### 1. Update Environment Configuration
+
+**File**: `.env`
+
+**Current (Development):**
+```bash
+# AgentBuilder API Base URL
+AGENTBUILDER_API_URL=http://localhost:8000
+```
+
+**Required (Production):**
+```bash
+# AgentBuilder API Base URL - PRODUCTION
+AGENTBUILDER_API_URL=https://agentsapi.chatslytics.com
+
+# Optional: Set log level for production
+LOG_LEVEL=info
+```
+
+**Action Required:**
+```bash
+cd /Users/shantanuchandra/code/agentbuilder/agentbuilder-mcp-server
+
+# Update .env file
+cat > .env << 'EOF'
+# AgentBuilder MCP Server Configuration - PRODUCTION
+
+# AgentBuilder API Base URL
+AGENTBUILDER_API_URL=https://agentsapi.chatslytics.com
+
+# Optional: Set default auth token (not recommended for security)
+# AGENTBUILDER_AUTH_TOKEN=your_supabase_jwt_token_here
+
+# Log level (info, debug, warn, error)
+LOG_LEVEL=info
+EOF
+```
+
+---
+
+### 2. Rebuild the Server
+
+```bash
+cd /Users/shantanuchandra/code/agentbuilder/agentbuilder-mcp-server
+
+# Install dependencies (if not already done)
+npm install
+
+# Rebuild with production config
+npm run build
+```
+
+---
+
+### 3. Update Claude Code Configuration
+
+**File**: `~/.claude/settings.local.json`
+
+**Current (Development):**
+```json
+{
+  "mcpServers": {
+    "agentbuilder": {
+      "command": "node",
+      "args": ["/Users/shantanuchandra/code/agentbuilder/agentbuilder-mcp-server/dist/index.js"],
+      "env": {
+        "AGENTBUILDER_API_URL": "http://localhost:8000"
+      }
+    }
+  }
+}
+```
+
+**Required (Production):**
+```json
+{
+  "mcpServers": {
+    "agentbuilder": {
+      "command": "node",
+      "args": ["/Users/shantanuchandra/code/agentbuilder/agentbuilder-mcp-server/dist/index.js"],
+      "env": {
+        "AGENTBUILDER_API_URL": "https://agentsapi.chatslytics.com",
+        "LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+**Action Required:**
+```bash
+# Edit Claude Code settings
+nano ~/.claude/settings.local.json
+
+# Or use this command to update automatically:
+cat > ~/.claude/settings.local.json << 'EOF'
+{
+  "mcpServers": {
+    "agentbuilder": {
+      "command": "node",
+      "args": ["/Users/shantanuchandra/code/agentbuilder/agentbuilder-mcp-server/dist/index.js"],
+      "env": {
+        "AGENTBUILDER_API_URL": "https://agentsapi.chatslytics.com",
+        "LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+EOF
+```
+
+---
+
+### 4. Set Up Production Authentication
+
+You have **2 options** for production authentication:
+
+#### Option A: OAuth 2.0 (Recommended for Production)
+
+**Steps:**
+
+1. **Login to AgentBuilder Production Dashboard:**
+   ```
+   https://agents.chatslytics.com
+   ```
+
+2. **Navigate to MCP Connections:**
+   - Go to **Settings** → **MCP Connections**
+   - Click **"Connect MCP"** button
+
+3. **Complete OAuth Flow:**
+   - Authenticate with Supabase
+   - Grant permissions
+   - Select target workspace
+
+4. **Copy Connection ID:**
+   - After OAuth success, copy connection ID
+   - Format: `mcp_conn_abc123xyz`
+
+5. **Use in Claude Code:**
+   ```
+   Connect to my AgentBuilder workspace using connection ID mcp_conn_abc123xyz
+   ```
+
+**Security Benefits:**
+- ✅ Workspace-scoped access
+- ✅ Automatic token refresh
+- ✅ AES-256-GCM encrypted storage
+- ✅ Multi-tenant isolation
+- ✅ No hardcoded tokens
+
+#### Option B: Direct JWT Token (Dev/Test Only)
+
+**⚠️ NOT RECOMMENDED for production use**
+
+**Steps:**
+
+1. **Get JWT Token:**
+   - Login to https://agents.chatslytics.com
+   - Open DevTools (F12)
+   - Application → Local Storage → supabase.auth.token
+   - Copy access_token value
+
+2. **Set in Claude Code:**
+   ```
+   Set AgentBuilder auth token to eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+   ```
+
+**Limitations:**
+- ❌ Token expires (needs manual refresh)
+- ❌ No workspace isolation
+- ❌ Security risk if token leaks
+- ❌ No automatic refresh
+
+---
+
+### 5. Verify Production Connection
+
+After setup, test the connection:
+
+```bash
+# In Claude Code, ask:
+"List my AgentBuilder workflows"
+```
+
+**Expected Response:**
+```
+✅ Connected to AgentBuilder Production API
+✅ Found X workflows in your workspace
+```
+
+**Or test with connection validation:**
+```
+# In Claude Code:
+"Test my AgentBuilder MCP connection"
+```
+
+---
+
+## 🔍 Verification Checklist
+
+Before using in production, verify:
+
+- [ ] `.env` updated with `https://agentsapi.chatslytics.com`
+- [ ] `npm run build` completed successfully
+- [ ] `~/.claude/settings.local.json` updated with production URL
+- [ ] Claude Code restarted
+- [ ] MCP server appears in available tools
+- [ ] Connection test succeeds
+- [ ] Can list workflows from production
+- [ ] Authentication working (OAuth or JWT)
+
+---
+
+## 🚨 Common Issues & Solutions
+
+### Issue 1: Connection Refused
+
+**Error:**
+```
+Error: connect ECONNREFUSED 127.0.0.1:8000
+```
+
+**Cause:** Still pointing to localhost
+
+**Solution:**
+```bash
+# Check .env file
+cat /Users/shantanuchandra/code/agentbuilder/agentbuilder-mcp-server/.env
+
+# Should show: https://agentsapi.chatslytics.com
+# If not, update it and rebuild:
+npm run build
+```
+
+### Issue 2: SSL Certificate Error
+
+**Error:**
+```
+Error: unable to verify the first certificate
+```
+
+**Cause:** SSL certificate validation issue
+
+**Solution:**
+```bash
+# Add to Claude Code settings env:
+"NODE_TLS_REJECT_UNAUTHORIZED": "0"  # Only for testing!
+
+# Better: Ensure production cert is valid
+curl https://agentsapi.chatslytics.com/health
+```
+
+### Issue 3: Authentication Failed
+
+**Error:**
+```
+Error: 401 Unauthorized
+```
+
+**Cause:** Invalid or expired token
+
+**Solution:**
+```bash
+# For OAuth: Re-do OAuth flow to get fresh connection
+# For JWT: Get new token from browser
+
+# Test backend auth manually:
+curl -H "Authorization: Bearer YOUR_TOKEN" \
+  https://agentsapi.chatslytics.com/api/v1/workflows
+```
+
+### Issue 4: CORS Error
+
+**Error:**
+```
+Access to XMLHttpRequest blocked by CORS policy
+```
+
+**Cause:** Backend CORS not allowing MCP requests
+
+**Solution:**
+```bash
+# Verify backend CORS config includes MCP origin
+kubectl get ingress agentbuilder-ingress -o yaml | grep cors
+
+# Should include localhost for development
+# For production, MCP runs locally so no CORS issue
+```
+
+### Issue 5: MCP Server Not Found in Claude Code
+
+**Error:**
+```
+No MCP tools available
+```
+
+**Cause:** Claude Code not loading MCP server
+
+**Solution:**
+```bash
+# 1. Check settings file exists
+cat ~/.claude/settings.local.json
+
+# 2. Verify path is correct
+ls -la /Users/shantanuchandra/code/agentbuilder/agentbuilder-mcp-server/dist/index.js
+
+# 3. Rebuild if needed
+cd /Users/shantanuchandra/code/agentbuilder/agentbuilder-mcp-server
+npm run build
+
+# 4. Restart Claude Code
+```
+
+---
+
+## 📊 Production vs Development Comparison
+
+| Aspect | Development | Production |
+|--------|-------------|------------|
+| **API URL** | http://localhost:8000 | https://agentsapi.chatslytics.com |
+| **Auth Method** | JWT Token (manual) | OAuth 2.0 (recommended) |
+| **Token Refresh** | Manual | Automatic |
+| **Workspace Isolation** | No | Yes |
+| **TLS/SSL** | No | Yes (Let's Encrypt) |
+| **CORS** | Localhost allowed | Not applicable (local MCP) |
+| **Logging** | Debug | Info/Warn |
+| **Token Storage** | Plain text | AES-256-GCM encrypted |
+
+---
+
+## 🔐 Security Best Practices
+
+### Production Deployment
+
+1. **Use OAuth 2.0, not JWT tokens**
+   - Tokens auto-refresh
+   - Workspace isolation
+   - Encrypted storage
+
+2. **Never commit tokens to git**
+   - `.env` is in `.gitignore`
+   - Use environment variables
+
+3. **Use HTTPS only**
+   - Production API: `https://agentsapi.chatslytics.com`
+   - Never use `http://` in production
+
+4. **Rotate tokens regularly**
+   - OAuth tokens refresh automatically
+   - Manual tokens should be rotated monthly
+
+5. **Monitor MCP access**
+   - Check backend logs for MCP activity
+   - Track workflow creation/execution
+
+---
+
+## 🚀 Quick Production Setup Script
+
+Run this script to set up production configuration:
+
+```bash
+#!/bin/bash
+
+# Quick production setup for AgentBuilder MCP Server
+
+MCP_DIR="/Users/shantanuchandra/code/agentbuilder/agentbuilder-mcp-server"
+CLAUDE_SETTINGS="$HOME/.claude/settings.local.json"
+
+echo "🚀 Setting up AgentBuilder MCP Server for Production..."
+
+# 1. Update .env
+echo "📝 Updating .env configuration..."
+cat > "$MCP_DIR/.env" << 'EOF'
+# AgentBuilder MCP Server Configuration - PRODUCTION
+AGENTBUILDER_API_URL=https://agentsapi.chatslytics.com
+LOG_LEVEL=info
+EOF
+
+# 2. Rebuild server
+echo "🔨 Building MCP server..."
+cd "$MCP_DIR"
+npm install
+npm run build
+
+# 3. Update Claude Code settings
+echo "⚙️  Updating Claude Code settings..."
+cat > "$CLAUDE_SETTINGS" << 'EOF'
+{
+  "mcpServers": {
+    "agentbuilder": {
+      "command": "node",
+      "args": ["/Users/shantanuchandra/code/agentbuilder/agentbuilder-mcp-server/dist/index.js"],
+      "env": {
+        "AGENTBUILDER_API_URL": "https://agentsapi.chatslytics.com",
+        "LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+EOF
+
+# 4. Test connection
+echo "🔍 Testing production API connection..."
+curl -s https://agentsapi.chatslytics.com/health | jq .
+
+echo ""
+echo "✅ Production setup complete!"
+echo ""
+echo "Next steps:"
+echo "1. Restart Claude Code"
+echo "2. Set up OAuth 2.0 connection (recommended)"
+echo "   - Visit: https://agents.chatslytics.com → Settings → MCP Connections"
+echo "   - Complete OAuth flow"
+echo "   - Copy connection ID"
+echo "3. In Claude Code, ask: 'Connect to AgentBuilder using connection ID mcp_conn_xxx'"
+echo ""
+echo "Or for quick test (dev/test only):"
+echo "1. Get JWT token from https://agents.chatslytics.com"
+echo "2. In Claude Code, ask: 'Set AgentBuilder auth token to <your-token>'"
+echo ""
+```
+
+**Save as:** `setup-production.sh`
+
+**Run:**
+```bash
+chmod +x setup-production.sh
+./setup-production.sh
+```
+
+---
+
+## 📝 Summary
+
+### What Needs to Change
+
+| File | Current Value | Required Value | Status |
+|------|--------------|----------------|--------|
+| `.env` | `http://localhost:8000` | `https://agentsapi.chatslytics.com` | ❌ Needs Update |
+| `~/.claude/settings.local.json` | `http://localhost:8000` | `https://agentsapi.chatslytics.com` | ❌ Needs Update |
+| Authentication | JWT (manual) | OAuth 2.0 (auto-refresh) | ⚠️ Recommended |
+
+### Deployment Priority
+
+1. **🔴 Critical** - Update API URL to production
+2. **🟡 High** - Rebuild MCP server (`npm run build`)
+3. **🟡 High** - Update Claude Code settings
+4. **🟢 Medium** - Set up OAuth 2.0 authentication
+5. **🟢 Medium** - Test production connection
+
+---
+
+## 🎯 Next Steps
+
+1. Run the quick setup script above
+2. Set up OAuth 2.0 connection in production dashboard
+3. Test workflow creation in Claude Code
+4. Deploy agents to production using MCP
+
+---
+
+**Last Updated**: 2026-01-26
+**Backend Version**: v20260126 (deployed)
+**MCP Server Version**: 0.2.0
+**Production API**: https://agentsapi.chatslytics.com