Umbrella MCP Server

# Umbrella MCP Server - Deployment Guide ## Overview This deployment guide covers setting up the Umbrella MCP Server as an HTTP(S) based service in the cloud that customers can connect to and authenticate with their Umbrella Cost credentials. ## Architecture ``` ┌─────────────────┐ HTTPS ┌─────────────────┐ API ┌─────────────────┐ │ LLM Client │ ◄────────► │ Umbrella MCP │ ◄────────► │ Umbrella Cost │ │ (Claude/GPT) │ │ Server │ │ API │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ## Deployment Options ### Option 1: Docker Container (Recommended) 1. Create a `Dockerfile`: ```dockerfile FROM node:18-alpine WORKDIR /app # Copy package files COPY package*.json ./ COPY tsconfig.json ./ # Install dependencies RUN npm ci --only=production # Copy source code COPY src/ ./src/ # Build the application RUN npm run build # Expose port EXPOSE 3000 # Create non-root user RUN addgroup -g 1001 -S nodejs RUN adduser -S nodejs -u 1001 # Change ownership RUN chown -R nodejs:nodejs /app USER nodejs # Start the server CMD ["npm", "start"] ``` 2. Build and run: ```bash docker build -t umbrella-mcp . docker run -p 3000:3000 \ -e UMBRELLA_API_BASE_URL=https://umbrellacost.io/api/v1 \ umbrella-mcp ``` ### Option 2: Cloud Platforms #### AWS ECS/Fargate 1. Create task definition with the Docker image 2. Set environment variables: - `UMBRELLA_API_BASE_URL=https://umbrellacost.io/api/v1` - `NODE_ENV=production` 3. Configure Application Load Balancer with HTTPS 4. Set up CloudWatch logging #### Google Cloud Run ```bash gcloud run deploy umbrella-mcp \ --image gcr.io/PROJECT_ID/umbrella-mcp \ --platform managed \ --set-env-vars UMBRELLA_API_BASE_URL=https://umbrellacost.io/api/v1 \ --allow-unauthenticated ``` #### Azure Container Instances ```bash az container create \ --resource-group myResourceGroup \ --name umbrella-mcp \ --image myregistry.azurecr.io/umbrella-mcp \ --environment-variables UMBRELLA_API_BASE_URL=https://umbrellacost.io/api/v1 \ --ports 3000 ``` ### Option 3: Traditional VPS/Server 1. Install Node.js 18+ 2. Clone the repository 3. Install dependencies: `npm install` 4. Build: `npm run build` 5. Set up environment variables 6. Use PM2 for process management: ```bash npm install -g pm2 pm2 start dist/index.js --name umbrella-mcp pm2 startup pm2 save ``` ## Configuration ### Environment Variables ```env # Required UMBRELLA_API_BASE_URL=https://umbrellacost.io/api/v1 MCP_SERVER_NAME=Umbrella MCP MCP_SERVER_VERSION=1.0.0 # Optional DEBUG=false NODE_ENV=production PORT=3000 ``` ### HTTPS Setup For production deployment, ensure HTTPS is enabled: #### Using nginx as reverse proxy: ```nginx server { listen 443 ssl; server_name your-domain.com; ssl_certificate /path/to/certificate.crt; ssl_certificate_key /path/to/private.key; location / { proxy_pass http://localhost:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } ``` ## Security Considerations ### Network Security - Deploy behind a firewall - Use HTTPS only - Implement rate limiting at the load balancer level - Consider IP whitelisting for enterprise customers ### Application Security - The server is read-only by design - No credentials are stored permanently - All authentication uses temporary tokens - Input validation on all parameters ### Monitoring - Set up health checks on `/health` endpoint - Monitor authentication success/failure rates - Track API usage patterns - Set up alerting for errors ## Client Connection ### LLM Client Configuration Customers connect their LLM clients (Claude, GPT, etc.) to the deployed MCP server: ```json { "mcpServers": { "umbrella": { "command": "node", "args": ["/path/to/umbrella-mcp/dist/index.js"], "env": { "UMBRELLA_API_BASE_URL": "https://umbrellacost.io/api/v1" } } } } ``` Or for HTTP-based connection: ```json { "mcpServers": { "umbrella": { "transport": "http", "url": "https://your-mcp-server.com" } } } ``` ## Authentication Flow 1. Customer connects to MCP server 2. Uses `authenticate` tool with Umbrella Cost credentials 3. Server obtains token from Umbrella Cost API 4. Token is used for subsequent API calls 5. Customer can ask natural language questions ## Testing Production Deployment ### Health Check ```bash curl -k https://your-server.com/health ``` ### MCP Server Test Use the built-in test runner: ```bash node dist/test-runner.js ``` ### Load Testing Use tools like Apache Bench or Artillery to test under load: ```bash ab -n 100 -c 10 https://your-server.com/health ``` ## Maintenance ### Log Monitoring Monitor logs for: - Authentication failures - API rate limit hits - Network connectivity issues - Performance bottlenecks ### Updates - Keep Node.js updated - Update MCP SDK regularly - Monitor Umbrella Cost API changes - Update dependencies for security patches ### Backup Since the server is stateless, focus on: - Configuration backup - Environment variables - SSL certificates - Deployment scripts ## Troubleshooting ### Common Issues 1. **Authentication failures**: Check credentials and network connectivity to Umbrella Cost API 2. **Rate limiting**: Implement exponential backoff and respect API limits 3. **SSL/TLS issues**: Verify certificates and cipher suites 4. **Memory usage**: Monitor Node.js heap usage, consider clustering ### Debug Mode Enable debug logging: ```env DEBUG=true NODE_ENV=development ``` ### Support Channels - Review server logs - Check Umbrella Cost API status - Monitor network connectivity - Contact Umbrella Cost support for API issues