Overview
Jeremiah Lowin, founder of Prefect and creator of fastmcp, explains why most MCP servers are poorly designed and how to build better ones. The core insight is that agents need curated interfaces optimized for their specific limitations, not just API wrappers that work for humans.
Key Takeaways
- Design for agent limitations, not human convenience - agents have expensive discovery (token cost on every handshake), slow iteration, and limited context windows unlike human developers
- Focus on outcomes, not operations - expose high-level workflows like ’track_latest_order’ rather than atomic API endpoints that force agents to orchestrate multiple calls
- Flatten complex arguments into primitives - avoid dictionaries and nested objects that confuse agents; use top-level strings, booleans, and enums with clear names
- Treat errors as prompts and examples as contracts - error messages become part of the agent’s next prompt, so make them helpful; agents will replicate patterns from examples exactly
- Curate ruthlessly to respect token budgets - keep servers under 50 tools per agent; a server with 800 endpoints leaves only ~25 tokens per tool description, lobotomizing the agent on handshake
Topics Covered
- 0:00 - Introduction and Background: Speaker introduction, fastmcp popularity (1.5M downloads yesterday), and positioning as the de facto MCP server framework
- 4:00 - Agentic Product Design Philosophy: Why agents need their own interfaces optimized for their strengths and weaknesses, not just human APIs
- 6:00 - Key Differences: Humans vs AI: Discovery is expensive for agents (token cost), iteration is slow, and context is limited compared to humans
- 13:30 - Fixing Bad MCP Servers: Live code review and refactoring example showing common problems with atomic operation exposure
- 15:00 - Design Principle 1: Outcomes Over Operations: Focus on what the agent wants to achieve, not exposing individual API endpoints as separate tools
- 18:30 - Design Principle 2: Flatten Arguments: Use simple primitives instead of complex dictionaries or nested objects that confuse agents
- 22:00 - Design Principle 3: Instructions as Context: Proper documentation, examples as contracts, and errors as prompts that guide agent behavior
- 27:30 - Design Principle 4: Token Budget Management: Real example of 800-endpoint API consuming entire context window, strategies for efficiency
- 35:30 - Design Principle 5: Curate Ruthlessly: Keep servers under 50 tools, progressive disclosure techniques, and Kelly’s Fiverr example (188 tools down to 5)
- 38:00 - Common Anti-Pattern: REST API Conversion: Why direct REST-to-MCP conversion violates all design principles, but can be useful for bootstrapping
- 40:00 - Summary and Q&A: Five key principles recap and audience questions about async tasks, elicitation, and code mode