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

Source references

• ^[src-013] Nate Herk — “Build & Sell Claude Code Operating Systems (2+ Hour Course)” (2026-05-01)
• ^[src-041] Marco Mornati — “The Future of Agentic Tooling: MCP Servers vs. CLI A Data-Driven Comparison” (2026-04-27)