Layered Server Architecture
Separate transport, handlers, and business logic.
Layered Server Architecture is a free MCP Academy lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the MCP Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Why One Big File Hurts
A server crammed into one file mixes transport, tool logic, and data calls. As it grows, every change risks breaking something far away.
Think in Layers
A clean server splits into layers: transport at the edge, MCP handlers in the middle, and pure business logic underneath.
The Transport Layer
The outer transport layer only moves messages, over stdio or HTTP. It should know nothing about what your tools actually do.
Handlers Are Thin Adapters
Your tool and resource handlers should be thin: parse arguments, call a service, shape the result. Keep real work out of them.
@mcp.tool()
def summarize(text: str) -> str:
return service.summarize(text)The Service Layer Does the Work
Put the actual logic in a plain service module with no MCP imports. It is just normal Python you can call from anywhere.
def summarize(text: str) -> str:
return shorten(clean(text))Why the Split Pays Off
With logic decoupled from MCP, you can test it without spinning up a server, and reuse it in a CLI or web app later.
Dependencies Point Inward
Keep the rule one-way: handlers may import services, but services must never import handlers or the transport above them.
A Folder Per Concern
Map layers to folders so the structure tells the story: server entry, handlers, services, and models each get their own place.
src/
server.py
handlers/
services/
models.pyRegister, Don't Define, in Entry
Your server.py should wire handlers to the FastMCP instance, not contain logic. It is an assembly point, not a workhorse.
from handlers import register_tools
register_tools(mcp)Cross-Cutting Helpers Stay Shared
Logging, config, and validation are shared concerns. Give them a common module so every layer uses the same helpers.
Grow Without Rewrites
Layering lets the server scale in size: add a new tool by adding a handler plus a service, leaving everything else untouched.
Quick Check
Where should the real business logic of a tool live?
Recap: Layered Design
Split your server into transport, thin handlers, and pure services, with dependencies pointing inward. Next: configuration. 🧱
Frequently asked questions
Is the “Layered Server Architecture” lesson free?
Yes — the full text of “Layered Server Architecture” is free to read here on the web, and the MCP Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the MCP Academy course, upgrade to CoddyKit PRO.
What will I learn in “Layered Server Architecture”?
Separate transport, handlers, and business logic. You practise MCP Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start MCP Academy?
No prior experience is required. MCP Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “Layered Server Architecture” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this MCP Academy lesson?
Yes. Every MCP Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- Layered Server Architecture
- Config & Secrets via Environment
- Idempotent, Side-Effect-Aware Tools
- Versioning Tools & Schemas