Misunderstanding FastMCP routing led to direct domain calls in FastAPI

In a FastAPI-based microservices architecture using FastMCP, developers inadvertently bypassed the orchestrator layer by making direct calls to domain-specific services. This violated the intended architectural separation, leading to inconsistencies in routing, tight coupling between components, and difficulties in debugging.

Issue

Developers made direct calls from the HTTP layer to domain services, such as calling payment_mcp_server.py directly instead of routing through the orchestrator (main_mcp_server.py). This caused:

• Routing inconsistencies: Middleware and prefix handling were bypassed.
• Tight coupling: The HTTP infrastructure was intertwined with domain logic.
• Duplicate functionality: Signature verification and other middleware were redundantly implemented.
• Debugging challenges: Tools were not found due to incorrect prefix resolution, leading to ToolNotFound errors.

The core issue was that tools like handle_stripe_webhook were called directly without the automatic prefix routing provided by FastMCP, causing failures when the orchestrator layer was bypassed.

Culprit

The root cause was a misunderstanding of FastMCP’s mounting system, where:

1. Direct Domain Calls: Developers treated domain services as standalone components rather than mounted modules, leading to direct API calls that bypassed the orchestrator.
2. Prefix Mismanagement: FastMCP automatically applies prefixes to tools when they are mounted, but developers were unaware of this mechanism and attempted to call tools without the required prefix.

Solution

Correct Routing Architecture

The architecture was corrected to enforce strict layer separation and proper routing through the orchestrator:

1. HTTP Layer: Handles infrastructure concerns such as signature verification, rate limiting, and deduplication. It delegates requests to the orchestrator but does not call domain services directly.
2. Orchestrator Layer: Manages middleware, server composition, and routing. It mounts domain services and ensures that all requests are properly prefixed and routed.
3. Domain Layer: Owns all domain-specific logic and configuration, with no involvement in HTTP-related concerns.

Key Changes

• HTTP Layer: Updated to delegate all requests to the orchestrator, ensuring proper routing and middleware application.
• Orchestrator Layer: Configured to mount domain services with appropriate prefixes, ensuring that all requests are correctly routed.
• Domain Layer: Consolidated all domain-specific logic and configuration, removing any HTTP-related responsibilities.

Verification

The fix was verified by:

1. Prefix Resolution: Confirming that calls to prefixed tools (e.g., payment_handle_stripe_webhook) correctly routed to the intended domain service.
2. Middleware Execution: Ensuring that orchestrator-level middleware was applied to all routed requests.
3. Isolation: Validating that domain-specific logic and configuration remained isolated from HTTP concerns.

This solution ensures that all requests are routed through the orchestrator layer, adhering to the intended architecture and improving reliability, maintainability, and debugging capabilities.