API over MCP Principle
Integration principle for AI operating systems: when an agent only needs a narrow set of actions from a service, direct API calls plus a curated reference file can be cheaper, faster, and more controllable than loading a full MCP server.
Key points
- MCP is valuable when broad tool discovery and standardised tool calling matter, but it carries context overhead because tool definitions enter the session [src-013]
- Direct APIs are often better for stable, high-frequency integrations where the agent needs only a small endpoint subset [src-013]
- A curated markdown reference listing the required endpoints gives the model enough operational context without exposing the full API surface [src-013]
- This pattern pairs naturally with the Scoped API Key Pattern: create a dedicated service account or narrowed token for the agent [src-013]
- The principle is especially relevant across the AIOS Tier-One Domains, where each connection should be deliberate rather than maximally broad [src-013]
- Mornati’s measurement reframes “API over MCP” as a frequency question: low-G/N services should avoid always-on schema injection, while high-G/N services can justify Native MCP [src-041]
- Gateway MCP adds a middle option: keep structured tool outputs without loading every backend service schema upfront [src-041]
Related entities
- ClickUp — example of using a direct API rather than the ClickUp MCP server
Related concepts
- MCP vs CLI Token Trade-off — broader context-efficiency tradeoff
- G/N Ratio Tool Selection — frequency-based decision heuristic for CLI, skill, gateway, or native MCP
- Gateway MCP Pattern — middle architecture between direct API/CLI and Native MCP
- Scoped API Key Pattern — security model for direct integrations
- Four C’s of an AI Operating System — Connections stage where this principle applies