MCP ARCHITECTURE DECISION

Comprehensive guidelines for AI-assisted development within the Editor platform

MCP Architecture Decision: Module vs Separate API

Decision ID: dev_1769090837831_j0ub80x Date: 2026-01-22 Session: 56.1 Status: APPROVED Confidence: 95%

Decision Summary

Question: Should we create a separate backend-mcp-api to handle all MCP operations?

Answer: NO - Keep MCP as an extractable module in backend-ai-api.

Context

The MCP (Model Context Protocol) Gateway provides HTTP/WebSocket access to mcp-gograb-ai capabilities for cloud users. As backend-ai-api grows with more AI generation features, the question arose whether MCP operations should be segregated into a separate API for cleaner responsibility separation.

Decision

Keep the current architecture:

backend-ai-api (port 3001)
└── McpGatewayModule          <- Extractable module
    ├── mcp-gateway.controller.ts
    ├── mcp-gateway.gateway.ts (WebSocket)
    ├── mcp-tools-bridge.service.ts
    ├── mcp-usage.service.ts
    ├── mcp-billing.service.ts
    └── tier-limit.guard.ts

The module is designed with clean boundaries and includes MCP_STANDALONE_MODE feature flag for future extraction.

Rationale

Why NOT create a separate API

Reason	Impact
70% infrastructure reuse	Shared auth, database config, WebSocket already exist
DRY principle	Would duplicate `@libs-api/backend-core` and `@libs-api/auth-core` setup
Tight coupling is intentional	MCP needs SuperIntelligence, Learning, CommandCenter modules
No traffic justification	No metrics show separation is needed
Already extractable	Feature flag enables future separation with zero refactoring

Why the current approach is correct

Prior Decision (Session 50.8) - This was already evaluated with 92% confidence
Operational simplicity - 2 APIs vs 3 APIs means less deployment overhead
Inter-service latency avoided - Direct method calls vs HTTP between services
Single authentication - Same JWT tokens work everywhere

Alternatives Considered

Option	Verdict	Reason
Independent microservice	REJECTED	Premature optimization
Module in backend-ai-api (extractable)	CHOSEN	Best of both worlds
NPM package only	REJECTED	Loses cloud gateway benefits
Separate cloud service	REJECTED	Adds unnecessary complexity

When to Revisit

Create a separate backend-mcp-api when ANY of these conditions are true:

Trigger	Threshold	Current Status
MCP traffic	> 100K requests/day	Not measured
Scaling requirements	Different profile needed	Same as backend-ai-api
Team ownership	Separate team for MCP	Single team
Regulatory isolation	Required by compliance	Not required
Revenue significance	Major revenue source	Early stage

See: MCP-EXTRACTION-CRITERIA.md for detailed criteria.

Implementation References

Current MCP Gateway Files

Feature Flag

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

Prior Documentation

Action Items Completed

Log decision via MCP log_decision tool
Document analysis in this file
Create extraction criteria document
Add observability to McpGatewayModule

Auto-generated from Session 56.1 architecture analysis