Geschichtete Serverarchitektur

A server crammed into one file mixes transport, tool logic, and data calls. As it grows, every change risks breaking something far away.

A clean server splits into layers: transport at the edge, MCP handlers in the middle, and pure business logic underneath.

The outer transport layer only moves messages, over stdio or HTTP. It should know nothing about what your tools actually do.

Your tool and resource handlers should be thin: parse arguments, call a service, shape the result. Keep real work out of them.

Put the actual logic in a plain service module with no MCP imports. It is just normal Python you can call from anywhere.

With logic decoupled from MCP, you can test it without spinning up a server, and reuse it in a CLI or web app later.

Keep the rule one-way: handlers may import services, but services must never import handlers or the transport above them.

Map layers to folders so the structure tells the story: server entry, handlers, services, and models each get their own place.

Your server.py should wire handlers to the FastMCP instance, not contain logic. It is an assembly point, not a workhorse.

Logging, config, and validation are shared concerns. Give them a common module so every layer uses the same helpers.

Layering lets the server scale in size: add a new tool by adding a handler plus a service, leaving everything else untouched.

Where should the real business logic of a tool live?

Split your server into transport, thin handlers, and pure services, with dependencies pointing inward. Next: configuration. 🧱