Finizi B4B MCP Server

# Deployment Guide - Finizi B4B MCP Server Complete guide for deploying and using the Finizi B4B MCP Server on Google Cloud Run. ## Production Server **Live Server**: https://finizi-b4b-mcp-600183975778.us-central1.run.app/mcp/ ### Quick Connect **Claude Code:** ```bash claude mcp add finizi-b4b https://finizi-b4b-mcp-600183975778.us-central1.run.app/mcp/ --transport http ``` **Claude Desktop:** Add to `claude_desktop_config.json`: ```json { "mcpServers": { "finizi-b4b": { "url": "https://finizi-b4b-mcp-600183975778.us-central1.run.app/mcp/", "transport": "http" } } } ``` --- ## Table of Contents - [Using the Server](#using-the-server) - [Deploying Your Own](#deploying-your-own) - [Configuration](#configuration) - [Monitoring](#monitoring) - [Troubleshooting](#troubleshooting) --- ## Using the Server ### With Claude Code #### Option 1: CLI Command (Recommended) ```bash claude mcp add finizi-b4b https://finizi-b4b-mcp-600183975778.us-central1.run.app/mcp/ --transport http ``` #### Option 2: Manual Configuration Edit `~/.config/claude-code/config.json`: ```json { "mcpServers": { "finizi-b4b": { "url": "https://finizi-b4b-mcp-600183975778.us-central1.run.app/mcp/", "transport": "http" } } } ``` Then restart Claude Code. ### With Claude Desktop Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on your OS: ```json { "mcpServers": { "finizi-b4b": { "url": "https://finizi-b4b-mcp-600183975778.us-central1.run.app/mcp/", "transport": "http" } } } ``` Restart Claude Desktop to load the server. ### With MCP Inspector (Testing) Test the server directly in your browser: ```bash npx @modelcontextprotocol/inspector https://finizi-b4b-mcp-600183975778.us-central1.run.app/mcp/ ``` This opens a web interface where you can: - View all 15 available tools - Test tool calls with custom parameters - See JSON-RPC request/response pairs - Debug authentication flows ### Testing the Connection Once connected, test with these commands in Claude: ``` 1. Login to the system 2. List my entities 3. Show me invoices from the last month ``` Expected tools to appear: - ✅ login, logout, whoami - ✅ list_entities, get_entity, create_entity, update_entity - ✅ list_invoices, get_invoice, import_invoice_xml, get_invoice_statistics - ✅ list_vendors, get_vendor - ✅ list_products, search_similar_products --- ## Deploying Your Own ### Prerequisites ### Required Tools - [Google Cloud SDK (gcloud)](https://cloud.google.com/sdk/docs/install) - [Docker](https://docs.docker.com/get-docker/) - A Google Cloud Project with billing enabled ### Google Cloud Setup 1. Create a Google Cloud Project (or use existing) 2. Enable required APIs: ```bash gcloud services enable \ run.googleapis.com \ containerregistry.googleapis.com \ cloudbuild.googleapis.com ``` 3. Authenticate with Google Cloud: ```bash gcloud auth login gcloud config set project YOUR_PROJECT_ID ``` ## Quick Start ### Option 1: Using the Deployment Script (Recommended) ```bash # Make the script executable chmod +x deploy.sh # Deploy to Cloud Run ./deploy.sh \ --project YOUR_PROJECT_ID \ --b4b-api-url https://your-b4b-api.example.com \ --region us-central1 # With authentication required ./deploy.sh \ --project YOUR_PROJECT_ID \ --b4b-api-url https://your-b4b-api.example.com \ --require-auth ``` ### Option 2: Manual Deployment ```bash # 1. Set your project export PROJECT_ID="your-project-id" export REGION="us-central1" export B4B_API_URL="https://your-b4b-api.example.com" # 2. Build the Docker image docker build -t gcr.io/$PROJECT_ID/finizi-b4b-mcp . # 3. Push to Google Container Registry docker push gcr.io/$PROJECT_ID/finizi-b4b-mcp # 4. Deploy to Cloud Run gcloud run deploy finizi-b4b-mcp \ --image gcr.io/$PROJECT_ID/finizi-b4b-mcp \ --region $REGION \ --platform managed \ --allow-unauthenticated \ --max-instances 10 \ --min-instances 0 \ --memory 512Mi \ --cpu 1 \ --timeout 60s \ --set-env-vars "B4B_API_BASE_URL=$B4B_API_URL,LOG_LEVEL=INFO" ``` ## Deployment Methods ### 1. Script-based Deployment (Easiest) Use the provided `deploy.sh` script: ```bash ./deploy.sh --help # View all options # Examples: ./deploy.sh -p my-project -b https://api.finizi.ai ./deploy.sh -p my-project -b https://api.finizi.ai -r europe-west1 ./deploy.sh -p my-project -b https://api.finizi.ai -l DEBUG --require-auth ``` ### 2. Google Cloud Build (CI/CD) For automated deployments, use Cloud Build with the provided `cloudbuild.yaml`: ```bash # Deploy via Cloud Build gcloud builds submit \ --config=cloudbuild.yaml \ --substitutions=_REGION=us-central1,_B4B_API_BASE_URL=https://your-api.example.com ``` ### 3. Manual gcloud Commands See the [Manual Deployment](#option-2-manual-deployment) section above. ## Configuration ### Environment Variables Configure the MCP server using environment variables. See `.env.example` for all options. #### Required Variables - `B4B_API_BASE_URL` - Base URL of your Finizi B4B API #### Optional Variables - `B4B_API_VERSION` - API version (default: `v1`) - `API_TIMEOUT` - Request timeout in seconds (default: `30`) - `API_CONNECT_TIMEOUT` - Connection timeout in seconds (default: `10`) - `MAX_RETRIES` - Maximum retry attempts (default: `3`) - `LOG_LEVEL` - Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL (default: `INFO`) - `RATE_LIMIT_REQUESTS` - Max requests per time window (default: `100`) #### Setting Environment Variables in Cloud Run ```bash # Via gcloud gcloud run services update finizi-b4b-mcp \ --region us-central1 \ --set-env-vars "B4B_API_BASE_URL=https://api.example.com,LOG_LEVEL=INFO" # Via deployment script ./deploy.sh -p my-project -b https://api.example.com -l DEBUG ``` ### Resource Configuration Adjust Cloud Run resources based on your needs: ```bash gcloud run services update finizi-b4b-mcp \ --region us-central1 \ --memory 1Gi \ --cpu 2 \ --max-instances 20 \ --min-instances 1 ``` ## Authentication ### Option 1: Allow Unauthenticated Access (Default) Good for testing or public APIs: ```bash ./deploy.sh -p my-project -b https://api.example.com --no-auth ``` ### Option 2: Require IAM Authentication (Recommended for Production) ```bash # Deploy with authentication required ./deploy.sh -p my-project -b https://api.example.com --require-auth # Grant invoker role to specific users/service accounts gcloud run services add-iam-policy-binding finizi-b4b-mcp \ --region us-central1 \ --member="user:alice@example.com" \ --role="roles/run.invoker" ``` ### Connecting MCP Clients with Authentication #### For Local Clients (Using Cloud Run Proxy) ```bash # Start the Cloud Run proxy gcloud run services proxy finizi-b4b-mcp --region us-central1 --port 3000 # Update your MCP client configuration { "mcpServers": { "finizi-b4b": { "url": "http://localhost:3000/mcp" } } } ``` #### For Programmatic Access (Using ID Tokens) ```python from google.auth.transport.requests import Request from google.oauth2 import id_token # Get ID token target_audience = "https://your-service-url.run.app" token = id_token.fetch_id_token(Request(), target_audience) # Include in requests headers = {"Authorization": f"Bearer {token}"} ``` ## Monitoring & Troubleshooting ### View Logs ```bash # Stream logs in real-time gcloud run logs tail finizi-b4b-mcp --region us-central1 # View recent logs gcloud run logs read finizi-b4b-mcp --region us-central1 --limit 100 # Filter by severity gcloud run logs read finizi-b4b-mcp --region us-central1 --log-filter="severity=ERROR" ``` ### Health Checks ```bash # Get service URL SERVICE_URL=$(gcloud run services describe finizi-b4b-mcp --region us-central1 --format 'value(status.url)') # Test health endpoint curl $SERVICE_URL/health # Test root endpoint curl $SERVICE_URL/ # Expected response: # {"status": "healthy", "service": "finizi-b4b-mcp", "version": "1.0.0"} ``` ### Common Issues #### 1. Service Not Starting ```bash # Check logs for errors gcloud run logs read finizi-b4b-mcp --region us-central1 --limit 50 # Common causes: # - Missing environment variables # - Invalid B4B API URL # - Port configuration issues ``` #### 2. Authentication Errors ```bash # Verify IAM permissions gcloud run services get-iam-policy finizi-b4b-mcp --region us-central1 # Add invoker role gcloud run services add-iam-policy-binding finizi-b4b-mcp \ --region us-central1 \ --member="user:YOUR_EMAIL" \ --role="roles/run.invoker" ``` #### 3. Timeout Issues ```bash # Increase timeout gcloud run services update finizi-b4b-mcp \ --region us-central1 \ --timeout 300s ``` ### Monitoring Dashboard View metrics in the Google Cloud Console: ``` https://console.cloud.google.com/run/detail/REGION/finizi-b4b-mcp/metrics ``` ## Best Practices ### 1. Security - ✅ **Require authentication** for production deployments - ✅ **Use HTTPS** for all connections (Cloud Run provides this automatically) - ✅ **Store secrets** in Google Secret Manager, not environment variables - ✅ **Limit IAM permissions** to only necessary users/services - ✅ **Enable VPC connector** if connecting to private B4B API ### 2. Performance - ✅ **Set appropriate resource limits** (CPU, memory) - ✅ **Use min-instances > 0** for latency-sensitive applications - ✅ **Configure max-instances** to prevent unexpected costs - ✅ **Monitor request latency** in Cloud Console ### 3. Reliability - ✅ **Enable health checks** (included in Dockerfile) - ✅ **Configure retries** via environment variables - ✅ **Set up alerts** for errors and high latency - ✅ **Use multiple regions** for high availability ### 4. Cost Optimization - ✅ **Set min-instances=0** for low-traffic services - ✅ **Right-size CPU/memory** allocation - ✅ **Monitor billing** in Cloud Console - ✅ **Use request-based pricing** to your advantage ### 5. Development Workflow ```bash # 1. Test locally with Docker docker build -t finizi-b4b-mcp . docker run -p 8080:8080 --env-file .env finizi-b4b-mcp # 2. Deploy to staging ./deploy.sh -p staging-project -b https://staging-api.example.com # 3. Test staging deployment curl https://staging-service.run.app/health # 4. Deploy to production ./deploy.sh -p prod-project -b https://api.example.com --require-auth ``` ## Using Your Deployed Server After deployment, add your server to MCP clients: ### Claude Code ```bash claude mcp add finizi-b4b https://YOUR-SERVICE-URL.run.app/mcp/ --transport http ``` ### Claude Desktop ```json { "mcpServers": { "finizi-b4b": { "url": "https://YOUR-SERVICE-URL.run.app/mcp/", "transport": "http" } } } ``` ### With Authentication Enabled If you deployed with `--require-auth`, use the Cloud Run proxy: ```bash # Start proxy gcloud run services proxy finizi-b4b-mcp --region us-central1 --port 3000 # Configure client { "mcpServers": { "finizi-b4b": { "url": "http://localhost:3000/mcp/", "transport": "http" } } } ``` ## Updating the Deployment ```bash # Update environment variables gcloud run services update finizi-b4b-mcp \ --region us-central1 \ --set-env-vars "LOG_LEVEL=DEBUG" # Deploy new version ./deploy.sh -p my-project -b https://api.example.com # Rollback to previous revision gcloud run services update-traffic finizi-b4b-mcp \ --region us-central1 \ --to-revisions PREVIOUS_REVISION=100 ``` ## Cost Estimation ### Cloud Run Pricing (us-central1) - **CPU**: $0.00002400 per vCPU-second - **Memory**: $0.00000250 per GiB-second - **Requests**: $0.40 per million requests - **Free Tier**: 2 million requests/month, 360,000 GiB-seconds ### Example Monthly Costs **Low Usage** (Personal/Development): - 10,000 requests/month - 10 hours active time - **Cost**: $0-1/month (covered by free tier) **Medium Usage** (Small Team): - 100,000 requests/month - 50 hours active time - **Cost**: $2-5/month **High Usage** (Production): - 1 million requests/month - 200 hours active time - **Cost**: $15-25/month With min-instances=0, the service scales to zero when not in use, minimizing costs. ## Server Information ### Current Production Deployment - **Service**: finizi-b4b-mcp - **URL**: https://finizi-b4b-mcp-600183975778.us-central1.run.app - **Region**: us-central1 - **Revision**: finizi-b4b-mcp-00009-gch - **Transport**: SSE (Server-Sent Events) - **Authentication**: Public (no auth required) ### Configuration ```yaml Memory: 512Mi CPU: 1 vCPU Timeout: 300s (5 minutes) Min Instances: 0 (scales to zero) Max Instances: 10 Concurrency: 80 requests/container ``` ### Environment Variables ```bash B4B_API_BASE_URL=https://be.dev.finizi.app LOG_LEVEL=INFO PORT=8080 (auto-configured by Cloud Run) ``` ## Support & Resources - **Cloud Run Documentation**: https://cloud.google.com/run/docs - **MCP Specification**: https://modelcontextprotocol.io - **Production Server**: https://finizi-b4b-mcp-600183975778.us-central1.run.app/mcp/ - **Health Endpoint**: https://finizi-b4b-mcp-600183975778.us-central1.run.app/health ## Next Steps 1. ✅ **Connect to the server** using instructions above 2. ✅ **Test the connection** with "Login to B4B and list my entities" 3. ✅ **Deploy your own** (optional) using the deployment script 4. ✅ **Configure authentication** if deploying with sensitive data 5. ✅ **Set up monitoring** for production deployments 6. ✅ **Add custom domain** (optional) for branded URLs --- **Status**: ✅ Production Ready **Version**: 1.0.0 **Last Updated**: 2025-10-02