MCP Design Patterns: Building Servers That Agents Can Actually Use

The Model Context Protocol has 97 million monthly SDK downloads. It is also blamed for hallucinating agents, context overflow, and unpredictable behavior.

The protocol is not the problem. Your server design is.

This is the thesis of Philipp Schmid, Technical Lead at Google DeepMind and creator of mcp-cli. His analysis reveals a fundamental error most developers make: treating MCP as a REST API wrapper.

The Mental Shift Required

MCP is not an API. It is a user interface for AI agents.

This distinction seems subtle but has profound consequences. Agents have different cognitive constraints than human developers:

Aspect	REST APIs (Developers)	MCP Tools (Agents)
Discovery	Cheap - read docs once	Expensive - schema loaded per request
Composition	Combine small endpoints freely	Multi-step calls slow iteration
Flexibility	More options = better DX	Complexity causes hallucination

When you port REST API patterns directly to MCP, you create granular CRUD operations that force agents into multi-step chains. Each additional tool consumes context, increases error chance, and slows the reasoning loop.

Six Essential Practices

1. Outcomes, Not Operations

The most common error: exposing infrastructure operations instead of results the agent needs.

Bad - three separate tools:

get_user_by_email(email)
list_orders(user_id)
get_order_status(order_id)

Good - one outcome-focused tool:

track_latest_order(email) -> {status, eta, tracking_url}

The agent’s goal is “track an order.” Give it a tool that does exactly that. Do not force the agent to orchestrate three calls to achieve a simple goal.

2. Flatten Your Arguments

Nested dictionaries are invitations for hallucination.

Bad - flexible structure:

search_orders(filters: dict)

Good - primitives with constraints:

search_orders(
    email: str,
    status: Literal["pending", "shipped", "delivered"],
    limit: int = 10
)

Constrained types reduce hallucination. The agent cannot invent invalid status values when the options are explicit.

3. Instructions Are Context

Every docstring, parameter description, and error message influences agent behavior. This is not documentation for humans — it is steering input for the model.

What to include:

When to use the tool
Expected input formats
Output structure
Helpful error messages, not technical exceptions

An agent that receives “status must be one of: pending, shipped, delivered” knows how to correct. One that receives “KeyError: status” does not.

4. Curate Ruthlessly

Target: 5-15 tools per server.

Each tool consumes context window space with its description, response schema, and potential error messages. Schmid advises: “Focus on discovery over exhaustive feature exposure.”

Reference point: Claude Code uses approximately 12 tools. Manus uses fewer than 20. These are production systems built by teams that understand context economics.

5. Name Tools for Discovery

Pattern: {service}_{action}_{resource}

Examples:

slack_send_message
linear_list_issues
sentry_get_error_details

Service prefixing prevents name collisions and helps agents understand tool provenance.

6. Paginate Large Results

Include limit parameter (default 20-50)
Return metadata: has_more, next_offset, total_count
Never load unbounded results into memory

Unpaginated results can overflow the agent’s context and cause erratic behavior.

Governance Through Design

Here is where MCP practices connect with AI governance:

Constrained types = agents cannot invent invalid values. This is not just good coding practice — it is a control mechanism that prevents unexpected behavior.

Outcome-focused tools = reduced attack surface. Fewer exposed operations means fewer vectors for prompt injection or misuse.

Curated tool sets = explicit capability boundaries. You know exactly what the agent can and cannot do.

Pagination = bounded resource consumption. The agent cannot consume unlimited resources in a single call.

This aligns with an AI governance philosophy: control comes from design constraints, not post-hoc monitoring.

The Enterprise Context

Most enterprise clients approaching MCP think in REST API terms. They have existing APIs and want to expose them to agents.

The educational conversation is this: “You are not building an API. You are designing a user interface for an entity with different cognitive constraints than your developers.”

This perspective shift is the first step toward MCP implementations that work.

Evaluation Checklist

Use these criteria to evaluate MCP servers:

Tool count:

Server has 15 or fewer tools?
Each tool serves a clear agent goal?

Tool design:

Tools are outcome-focused, not operation-focused?
Arguments are primitives with constrained types?
Names follow service_action_resource pattern?

Context and documentation:

Descriptions explain when to use each tool?
Input/output formats are documented?
Error messages are actionable?

Resource management:

Large results are paginated?
Default limits are reasonable (20-50)?
Pagination metadata is included?

Alternatives and Complements

Schmid’s practices are not the only approaches. Also consider:

Tool RAG: Semantic search across large tool indexes, loading only relevant tools per task. This allows larger tool sets without overloading context.

Dynamic Tool Masking: Manus’s approach — keep many tools but control visibility via state machines. Tools appear only in appropriate contexts.

Hierarchical Organization: Meta-tools that expose sub-capabilities on demand. “database_query” can expand to specific operations when needed.

These approaches are complementary, not exclusive. Aggressive curation is the starting point; advanced techniques allow scaling.

Security Considerations

The original article focuses on performance optimization. For enterprise, add:

Authentication and Authorization: MCP has no inherent security mechanisms. OAuth 2.1, least privilege, and input validation are the implementer’s responsibility.

Audit Trails: Log all tool calls for compliance and debugging.

Tool Governance: Versioning, lifecycle management, and change control for production tools.

Attack Surface: Each tool is a potential vector. Minimize exposure, validate inputs, and consider sandboxing for sensitive operations.

Conclusion

MCP has 97 million monthly downloads. Adoption will only grow. The difference between implementations that work and those that frustrate lies in design.

Stop exposing infrastructure. Start designing outcomes.

The best MCP servers do not feel like APIs. They feel like purpose-built tools that understand what the agent is trying to accomplish.

Six practices. Evaluation checklist. User interface mindset, not API mindset.

That is the path to MCP servers that agents can actually use.

At Victorino Group, we implement MCP with governance for companies that need reliable agents. If you want servers that work and that you control, let’s talk.