Best Practices

This guide provides recommended patterns, optimizations, and best practices for using Storm MCP Gateway effectively in production environments.

Architecture Best Practices

Gateway Design Patterns

1. Purpose-Driven Gateways

Create focused gateways for specific workflows:

Good Pattern:

Development Gateway
├── GitHub (version control)
├── Docker (containers)
├── PostgreSQL (database)
└── Sentry (error tracking)

Marketing Gateway
├── HubSpot (CRM)
├── Mailchimp (email)
├── Google Analytics (analytics)
└── Social Media APIs

Anti-Pattern:

Everything Gateway ❌
├── All 30+ services
├── All functions enabled
├── No clear purpose
└── Difficult to manage

2. Environment Separation

Maintain separate gateways for each environment:

my-app-dev
├── Dev database
├── Staging APIs
└── Debug logging enabled

my-app-prod
├── Production database
├── Production APIs
└── Minimal logging

3. Team Boundaries

Organize gateways by team responsibility:

frontend-team/
├── gateway-ui-services
└── gateway-cdn-apis

backend-team/
├── gateway-databases
└── gateway-microservices

devops-team/
├── gateway-infrastructure
└── gateway-monitoring

Scaling Strategies

Horizontal Scaling

Distribute load across multiple gateways:

// Load balancing configuration
{
  "gateways": [
    { "id": "gateway-1", "weight": 33 },
    { "id": "gateway-2", "weight": 33 },
    { "id": "gateway-3", "weight": 34 }
  ],
  "strategy": "round-robin"
}

Vertical Scaling

Optimize individual gateway performance:

Minimize Server Count
- Each server adds overhead
- Group related services
- Remove unused servers
Function Optimization
- Disable unused functions
- Reduces token usage
- Improves response time
Caching Strategy
- Cache frequent queries
- Set appropriate TTLs
- Monitor cache hit rates

Security Best Practices

Authentication & Authorization

API Key Management

Do:

// Store keys securely
process.env.STORM_API_KEY

// Rotate regularly
const keyAge = Date.now() - keyCreated;
if (keyAge > 90 * 24 * 60 * 60 * 1000) {
  rotateApiKey();
}

// Use descriptive names
"prod-claude-desktop-key"
"dev-cursor-integration"

Don't:

// Never hardcode keys
const apiKey = "sk-abc123..."; ❌

// Never commit to version control
git add .env ❌

// Never share keys between environments
dev.apiKey === prod.apiKey ❌

Principle of Least Privilege

Grant minimum necessary permissions:

// Good: Specific permissions
{
  "github": {
    "functions": [
      "repos_list_issues",
      "repos_create_issue"
    ],
    "blocked": ["repos_delete", "admin_*"]
  }
}

// Bad: Everything allowed
{
  "github": {
    "functions": "*" ❌
  }
}

Network Security

IP Whitelisting

Restrict access to known IPs:

{
  "security": {
    "ip_whitelist": [
      "203.0.113.0/24",  // Office network
      "198.51.100.5/32", // CI/CD server
      "192.0.2.0/24"     // VPN range
    ]
  }
}

Rate Limiting

Prevent abuse with rate limits:

{
  "rate_limits": {
    "per_minute": 100,
    "per_hour": 1000,
    "per_day": 10000,
    "burst": 20
  }
}

Encryption

Ensure all data is encrypted:

In Transit - TLS 1.3 for all connections
At Rest - AES-256 for stored credentials
Secrets - Use secret management service

Audit & Compliance

Logging Strategy

Comprehensive but compliant logging:

{
  "logging": {
    "level": "info",
    "include": ["timestamp", "user", "action", "result"],
    "exclude": ["password", "api_key", "personal_data"],
    "retention_days": 90,
    "compliance": ["GDPR", "HIPAA"]
  }
}

Access Reviews

Regular security audits:

Monthly Reviews
- Check active API keys
- Review user permissions
- Audit gateway access
Quarterly Audits
- Full security assessment
- Penetration testing
- Compliance verification

Performance Optimization

Response Time Optimization

Function Selection

Choose only necessary functions:

// Before: 245ms average
{
  "github": {
    "functions": "*" // 150+ functions
  }
}

// After: 95ms average
{
  "github": {
    "functions": [
      "repos_get",
      "issues_create",
      "pulls_list"
    ] // Only 3 functions
  }
}

Caching Strategy

Implement intelligent caching:

{
  "cache": {
    "enabled": true,
    "strategies": {
      "user_data": { "ttl": 3600 },    // 1 hour
      "repo_list": { "ttl": 300 },     // 5 minutes
      "static_config": { "ttl": 86400 } // 24 hours
    }
  }
}

Connection Pooling

Reuse connections efficiently:

{
  "connections": {
    "pool_size": 10,
    "idle_timeout": 30000,
    "max_lifetime": 3600000,
    "validation_interval": 60000
  }
}

Token Usage Optimization

Reduce AI token consumption:

1. Selective Function Exposure

// High token usage (bad)
gateway.functions.count = 500 // All functions from all apps

// Low token usage (good)
gateway.functions.count = 25 // Only essential functions

2. Function Descriptions

Optimize function documentation:

// Verbose (wastes tokens)
{
  "name": "create_github_issue",
  "description": "This function creates a new issue in a GitHub repository. It requires the repository owner, repository name, issue title, and issue body. Optional parameters include labels, assignees, and milestone..."
}

// Concise (saves tokens)
{
  "name": "create_github_issue",
  "description": "Create GitHub issue",
  "required": ["owner", "repo", "title", "body"]
}

3. Response Filtering

Return only necessary data:

{
  "response_filter": {
    "include": ["id", "status", "result"],
    "exclude": ["metadata", "debug_info", "raw_response"]
  }
}

Database Optimization

For database MCP servers:

Query Optimization

-- Bad: Full table scan
SELECT * FROM users WHERE email LIKE '%@example.com';

-- Good: Indexed query
SELECT id, name, email FROM users 
WHERE domain = 'example.com' 
LIMIT 100;

Connection Management

{
  "database": {
    "max_connections": 20,
    "connection_timeout": 5000,
    "idle_timeout": 60000,
    "statement_cache_size": 100
  }
}

Operational Best Practices

Monitoring & Alerting

Key Metrics to Track

Golden Signals
- Latency (response time)
- Traffic (requests/second)
- Errors (error rate)
- Saturation (resource usage)
Business Metrics
- Function usage
- User activity
- Cost per operation
- SLA compliance

Alert Configuration

Avoid alert fatigue:

{
  "alerts": {
    "critical": {
      "error_rate": "> 5%",
      "response_time": "> 2000ms",
      "availability": "< 99.9%"
    },
    "warning": {
      "error_rate": "> 1%",
      "response_time": "> 1000ms",
      "availability": "< 99.95%"
    }
  }
}

Deployment Best Practices

Blue-Green Deployments

Zero-downtime updates:

1. Create new gateway (green)
2. Test thoroughly
3. Switch traffic gradually
4. Monitor metrics
5. Complete switch or rollback

Configuration as Code

Version control your configurations:

# gateway-config.yaml
name: production-gateway
servers:
  - github:
      version: v1.2.3
      functions:
        - repos_get
        - issues_create
  - slack:
      version: v2.0.1
      functions:
        - chat_postMessage

Rollback Strategy

Quick recovery from issues:

{
  "deployment": {
    "strategy": "canary",
    "rollback_triggers": {
      "error_rate": "> 10%",
      "response_time": "> 3000ms"
    },
    "auto_rollback": true
  }
}

Documentation Standards

Gateway Documentation

Document each gateway:

# Gateway: production-api

## Purpose
Main production gateway for customer-facing APIs

## Servers
- GitHub: Repository management
- Stripe: Payment processing
- SendGrid: Email delivery

## SLA
- Availability: 99.95%
- Response time: < 500ms p95

## Contacts
- Owner: platform-team@company.com
- On-call: platform-oncall@pagerduty.com

Runbook Creation

Operational runbooks for common issues:

# Runbook: High Error Rate

## Symptoms
- Error rate > 5%
- Alerts firing in #alerts channel

## Diagnosis
1. Check /observability for error patterns
2. Review recent deployments
3. Check upstream service status

## Resolution
1. If deployment-related: rollback
2. If upstream issue: enable circuit breaker
3. If load-related: scale horizontally

Client Integration Best Practices

Claude Desktop Integration

Optimal Configuration

{
  "mcp_servers": {
    "storm_gateway": {
      "command": "node",
      "args": ["@storm-mcp/client"],
      "env": {
        "STORM_GATEWAY_URL": "${GATEWAY_URL}",
        "STORM_LOG_LEVEL": "warn",
        "STORM_CACHE_ENABLED": "true"
      }
    }
  }
}

Error Handling

Graceful degradation:

try {
  const result = await gateway.execute(function);
  return result;
} catch (error) {
  if (error.code === 'RATE_LIMITED') {
    await delay(error.retryAfter);
    return retry();
  }
  // Fallback behavior
  return getFromCache() || defaultResponse;
}

Cursor IDE Integration

Workspace Configuration

Organize MCP configurations:

.cursor/
├── mcp-config.json       # Main configuration
├── mcp-dev.json         # Development overrides
└── mcp-functions.json   # Custom functions

Performance Settings

{
  "mcp": {
    "timeout": 30000,
    "retries": 3,
    "cache": {
      "enabled": true,
      "ttl": 300
    },
    "parallel_requests": 5
  }
}

Cost Optimization

Resource Management

Token Usage Reduction

Function Pruning
- Remove unused functions
- Shorter descriptions
- Efficient schemas
Response Optimization
- Return only needed fields
- Compress responses
- Use pagination
Caching Strategy
- Cache expensive operations
- Share cache across gateways
- Monitor cache effectiveness

API Call Optimization

Reduce external API calls:

{
  "optimization": {
    "batch_requests": true,
    "deduplication": true,
    "prefetch_common": true,
    "lazy_load_rare": true
  }
}

Cost Monitoring

Track and optimize costs:

{
  "cost_tracking": {
    "budgets": {
      "monthly": 1000,
      "daily": 35,
      "per_user": 10
    },
    "alerts": {
      "80_percent": "warning",
      "90_percent": "critical",
      "exceeded": "block_new_requests"
    }
  }
}

Migration Best Practices

Upgrading Gateways

Safe upgrade process:

Test in Development
- Create dev gateway copy
- Test all functions
- Verify compatibility
Staged Rollout
- 10% traffic → monitor
- 50% traffic → verify
- 100% traffic → complete
Rollback Plan
- Keep old gateway active
- One-click rollback ready
- Document rollback steps

Moving Between Environments

# Export configuration
storm-mcp export --gateway dev-gateway > config.json

# Modify for production
sed -i 's/dev-/prod-/g' config.json

# Import to production
storm-mcp import --env production < config.json

Troubleshooting Guide

Common Issues

Gateway Not Responding

# Check health
curl https://gateway.stormmcp.ai/health

# Verify authentication
curl -H "Authorization: Bearer $API_KEY" \
  https://api.stormmcp.ai/v1/gateways/YOUR_ID

# Test specific function
storm-mcp test --gateway YOUR_ID --function test_connection

High Latency

Check function count (reduce if > 50)
Review server locations (use closest region)
Enable caching
Check rate limits

Authentication Failures

Verify API key not expired
Check IP whitelist
Review permissions
Test with new key

Checklists

Production Readiness Checklist

Authentication configured
Rate limits set
Monitoring enabled
Alerts configured
Backup gateway created
Documentation complete
Runbooks written
Team trained
SLA defined
Rollback plan ready

Security Checklist

API keys rotated quarterly
Least privilege enforced
IP whitelist configured
Audit logging enabled
Encryption verified
Compliance checked
Access reviews scheduled
Incident response plan

Performance Checklist

Functions optimized
Caching enabled
Connection pooling configured
Response filtering active
Token usage monitored
Load testing completed
Scaling plan defined
Cost tracking enabled

Next Steps

Apply these best practices: