Clarify and strengthen layering between FastMCP and low-level server

[dgenio]

Description

Summary

FastMCP provides a higher-level API over the low-level MCP server, but the layering between them is currently leaky:

• FastMCP wraps an internal _mcp_server object and manually translates decorators into low-level handler registrations.
• Tests and some user code refer directly to server._mcp_server, bypassing the abstraction.
• New MCP features often require changes in both layers, with duplicated logic.

This issue proposes a clearer, more robust layering between:

1. the protocol / low-level server,
2. a handler/dispatch layer, and
3. the FastMCP convenience API.

Problems

• Encapsulation: _mcp_server is visible and sometimes accessed directly, which makes refactors risky.
• Maintenance overhead: Every new feature in the low-level server must be manually threaded through FastMCP.
• User confusion: It is not obvious when developers should use FastMCP vs. the low-level API, or how to mix them safely.

Proposal

1. Define FastMCP as a proper facade

   • Treat FastMCP as the stable, recommended API for most Python MCP servers.
   • Avoid exposing _mcp_server on the public surface; tests and examples should use only the FastMCP API.
   • Provide explicit escape hatches (documented hooks) instead of relying on private attributes.

2. Clarify the layering

   • Consider separating the low-level server into:
     • a protocol layer (pure MCP message handling),
     • a handler/dispatch layer (registration, routing, context),
     • the FastMCP “ergonomic” layer (decorators, automatic schema generation).
   • Each layer should have a well-defined responsibility and be usable independently.

3. Document usage patterns

   • Add a short “When to use FastMCP vs low-level server” section to the docs.
   • Show how advanced users can opt into lower-level APIs without depending on private attributes.

Why this matters

• Stability: Clear boundaries make it easier to evolve FastMCP and the underlying server independently.
• Usability: Most users can stay within FastMCP and not worry about internal details.
• Maintenance: Reduces the risk of subtle breakages when low-level internals change.

Acceptance criteria

• [ ] FastMCP’s public API is documented as the recommended server API for typical use cases.
• [ ] Direct access to _mcp_server is removed from examples/tests (or clearly marked as internal).
• [ ] A layering diagram or equivalent documentation describes how protocol, handler, and FastMCP layers fit together.
• [ ] New MCP features can generally be added by touching a single layer at a time.

References

No response