Agent Surface pattern proposes MCP as a first-class API layer for AI agents

Saulo Santos opens by framing two universal problems facing software organizations today: how to bridge existing applications into the AI world, and how to design new ones as AI-ready from the start. He traces a historical pattern — REST emerged for generic clients, GraphQL for flexible UI queries, gRPC for high-volume service-to-service communication — and argues that each new consumer class produced a dedicated protocol layer. AI agents are the latest such consumer class, and they are currently being served with surfaces designed for humans and deterministic machines, resulting in brittle glue code and expensive runtime rediscovery.

The proposed "Agent Surface" pattern names six forces it resolves.

The proposed "Agent Surface" pattern names six forces it resolves. On discoverability, Santos argues that LLM-based agents are the first consumer class capable of acting on a self-describing surface at runtime — fulfilling the original HATEOAS promise that arrived "twenty years before its consumer did." On granularity, he notes that a single agent-level intent like "bind a quote" may span multiple REST operations, forcing agents to rediscover workflow conventions expensively and incorrectly. On economics, he frames every undescribed workflow convention as a perpetual runtime token cost paid on every call by every agent. On legacy reality, he explicitly requires the pattern to be additive — any approach requiring a rewrite is "dead on arrival" for the large Spring Boot and Jakarta EE estates that hold real enterprise business capabilities. The pattern's stated structure extends ports-and-adapters thinking, though the source text is truncated before the structural details are fully described.

Key facts

1. 01Saulo Santos proposes the 'Agent Surface' pattern: a dedicated MCP layer treated as co-equal with REST, GraphQL, and gRPC.
2. 02The pattern applies to both greenfield services (designed in from day one) and brownfield ones (added as an incremental layer).
3. 03Six forces drive the pattern: discoverability, granularity mismatch, security, operational access, token economics, and legacy reality.
4. 04Santos argues LLM-based agents are the first consumer class that can act on a self-describing surface at runtime, fulfilling the original HATEOAS promise.
5. 05A granularity mismatch example: a single agent intent ('bind a quote') may require a POST, a PUT, and another POST across three separate REST endpoints.
6. 06Undescribed workflow conventions are framed as a perpetual token cost paid on every agent call, forever.
7. 07The pattern must be additive and require no rewrite to be viable in large Spring Boot and Jakarta EE enterprise estates.

Topics