Agent-Native MCP Architecture Notes

This note captures the architecture decisions behind the agent-native MCP servers so future MCP servers can reuse the same shape. It is not a code guide. It is a design guide for making an MCP pleasant for agents and useful for humans.

Goal

Build MCP servers as agent-native interface surfaces, not thin document dumps.

An agent should be able to discover what the server knows, choose the right tool, make a compact first call, fetch the exact source it needs, and explain the result with provenance. The server should reduce reasoning overhead by exposing the domain model, the workflow, and the next action at each step.

Core Principles

The server should make the correct path obvious.

Good agent ergonomics come from a small number of clear tools, stable response shapes, compact search results, and explicit next steps. The agent should not need to infer hidden sequencing from failures.

The server should separate discovery, retrieval, and source context.

Discovery tells the agent what exists and how to use it. Search finds compact candidates. Fetch returns full source-backed artifacts. Combining these into one large response wastes context and makes agents less reliable.