Design Principles: API vs MCP
summary
Claims that APIs assume deterministic clients and agents are reasoning systems lead to four actionable design rules: expose capabilities not primitives (eg. replace four-step deploy endpoints with a single deploy application capability), prefer intent-based interfaces with explicit JSON schemas (require a “reason” field), keep capability surface small (10 tools ≈ 3–8k tokens vs 100 tools ≈ 10× cost), and log observable operational intent into DBs, structured logs or tracing for auditability and troubleshooting.
AI-written summary · about
chapters (12)
- 0:00MCP design principles intro
- 1:27MCP servers expose API endpoints
- 3:17MCP changes agent execution
- 6:30MCP for contextual agents
- 8:35REST SOAP gRPC agent limits
- 11:50Anti-patterns in MCP servers
- 14:21Principle: Capabilities over primitives
- 18:34Principle: Intent-based interfaces
- 23:55Principle: Minimal capability surfaces
- 26:25Principle: Observable intent
- 31:41APIs and MCP harmony
- 33:48Summary
related talks
26mGovernance and Security of APIs and MCPs
21mScaling API Design
35mUnleash Your Inner API Architect: Build Agents That Deliver
47mAPI Design Principles
24mThe API Economy's Next Chapter: AI Agents as First-Class Clients
33mDesigning Sustainable APIs
01h 36mThe Most Important API Design Guideline - No, It's Not That One
17mBuilding Production-Ready MCP Servers: From AI Agents to Secure Enterprise APIs.