Design Principles — Why Most MCP Servers Are Wrong
Learn the design framework for building MCP servers that AI agents actually want to use.
Quick actions
Try the app, view the code, or explore the components.
By the end of this lesson, you will:
- Understand why most MCP servers are designed wrong
- Learn the design framework: empathize, find true tasks, design tools
- See the Notion MCP server as a case study
- Apply design principles to your own servers
The Problem with Most MCP Servers
Most developers approach MCP servers like API wrappers:
❌ "I'll expose every Notion API endpoint as a tool"
This is wrong. Here's why.
Your Client is an AI Agent
The AI doesn't want raw API access. It wants to accomplish tasks.
When a user says "Create meeting notes for my standup," the AI needs:
- A tool that understands what "meeting notes" means
- Sensible defaults (date, template, location)
- Context about the user's workspace
Not 47 granular API endpoints.
The Design Framework
- Empathize with the agent — What is it actually trying to accomplish?
- Find the true tasks — What are the 3-5 things users actually do?
- Design tools that match — Atomic but complete, self-describing, predictable
Notion Server Example
Instead of exposing every Notion API method, we designed around real tasks:
| User Intent | Tool Design |
|---|---|
| "Find my notes" | search_pages(query) — Smart search with context |
| "Create a page" | create_page(title, content, parent?) — Sensible defaults |
| "Update something" | update_page(id, changes) — Partial updates |
Each tool does one thing well, with good defaults.
Key Principles
1. Atomic but Complete
One tool, one job, full result. No sequential calling required.
2. Self-Describing
Tool names and descriptions tell the agent WHEN to use it, not just what it does.
3. Predictable
Same inputs always produce same output shape. Agents can reason about structure.
Try It Yourself
Experience the difference between a well-designed MCP server and a raw API wrapper.