MCP: align runtime with FastMCP-first architecture #4
Description
Summary
The MCP server is presented as a FastMCP server, but the current implementation still depends on a FastAPI wrapper for lifespan, health routes, middleware, and webhook mounting.
This creates confusion for contributors and deployment complexity for maintainers.
Problem
The current architecture mixes:
- FastMCP tool server
- FastAPI application wrapper
- FastAPI lifecycle hooks
- FastAPI-specific exception and webhook handling
This makes the MCP server harder to understand, harder to test, and harder to evolve.
What needs to happen
- decide whether the MCP server is:
- truly FastMCP-first, or
- FastMCP mounted inside FastAPI by design
- clean up the runtime to match that decision
- document the architecture clearly
Acceptance criteria
- runtime architecture is clearly defined
- unnecessary FastAPI coupling is removed or clearly documented
- startup and shutdown behavior is consistent
- local run path and production run path are documented