MCP Extraction Criteria

Document: When to extract McpGatewayModule to backend-mcp-api Created: 2026-01-22 Session: 56.1 Status: Reference document for future evaluation

Overview

The McpGatewayModule in backend-ai-api is designed to be extractable. This document defines the specific, measurable criteria that would trigger extraction to a separate backend-mcp-api microservice.

Extraction Triggers

Extract when ANY of these conditions are met:

1. Traffic Volume

Current: Not measured. Add observability first.

2. Performance Isolation

Current: No symptoms observed.

3. Scaling Requirements

Current: Single instance sufficient.

4. Team/Organizational

Current: Single team, unified release.

5. Revenue/Business

Current: Integrated with GoGrab Space.

How to Measure (Observability Checklist)

Before extraction can be evaluated, implement these metrics:

Required Metrics

// Add to McpGatewayModule or use external APM
interface McpMetrics {
  // Request metrics
  requestCount: Counter;           // Total requests
  requestDuration: Histogram;      // Latency distribution
  requestErrors: Counter;          // Error count by type

  // Resource metrics
  activeConnections: Gauge;        // WebSocket connections
  memoryUsage: Gauge;              // MCP-specific memory

  // Business metrics
  uniqueUsers: Gauge;              // DAU for MCP
  toolUsageByName: Counter;        // Which tools are popular
  tierBreakdown: Counter;          // Free vs paid usage
}

Logging Requirements

// Structured logs for analysis
{
  level: 'info',
  service: 'mcp-gateway',
  event: 'tool_call',
  tool: 'preflight',
  userId: 'xxx',
  spaceId: 'xxx',
  durationMs: 45,
  success: true,
  tier: 'builder'
}

Dashboard Requirements

• Daily/weekly/monthly request trends
• P50, P95, P99 latency over time
• Error rate by tool
• Usage by tier (free/builder/pro/enterprise)
• Top users by volume

Extraction Process (When Triggered)

Step 1: Preparation

1. Ensure all metrics are in place
2. Document current baseline performance
3. Identify all integration points

Step 2: Create New API

# Generate new NestJS application
nx generate @nx/nest:application backend-mcp-api

# Copy McpGatewayModule
cp -r apis/backend-ai-api/src/app/mcp-gateway apis/backend-mcp-api/src/app/

# Update imports to use shared libs
# @libs-api/backend-core
# @libs-api/auth-core

Step 3: Configure Infrastructure

// apis/backend-mcp-api/src/app/app.module.ts
@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    AuthCoreModule.forRoot({ /* same config */ }),
    MongooseModule.forRootAsync({ /* same databases */ }),
    ThrottlerModule.forRoot(AI_THROTTLE_CONFIG),
    McpGatewayModule,  // Now the main module
  ],
})
export class AppModule {}

Step 4: Update Integration Points

1. Update frontend to call new API endpoint
2. Update backend-ai-api to remove McpGatewayModule
3. If needed, create HTTP client for cross-service calls

Step 5: Deploy and Validate

1. Deploy to staging with feature flag
2. Run load tests to compare performance
3. Gradual rollout with traffic splitting
4. Monitor for regressions

Estimated Effort

Total: 2-4 days (when criteria are met)

Feature Flag

The module already includes extraction preparation:

// McpGatewayModule providers
{
  provide: 'MCP_STANDALONE_MODE',
  useValue: process.env.MCP_STANDALONE_MODE === 'true' || false,
}

When MCP_STANDALONE_MODE=true:

• Module operates independently
• Reduced dependency on other backend-ai-api modules
• Ready for extraction

Decision History

Review Schedule

Re-evaluate this decision:

• Monthly during rapid growth phases
• Quarterly during stable operations
• Immediately if any trigger threshold is approached

Created from Session 56.1 architecture analysis. Decision ID: dev_1769090837831_j0ub80x