MCP Server Design: How to Build Tools Agents Can Use Safely
An MCP server is a capability boundary. Good design keeps tools narrow, explicit, validated, and easy to audit.
An MCP server is a capability boundary. Good design keeps tools narrow, explicit, validated, and easy to audit.
Design MCP servers like production APIs, not unrestricted bridges into internal systems.
An MCP server is a capability boundary between an AI client and software that can perform real actions.
That makes server design important. A poorly designed MCP server can turn a useful agent integration into an unrestricted bridge to databases, APIs, files, or internal systems.
Prefer business operations such as search_orders, create_ticket, and get_customer_status over a generic execute_query or HTTP request tool.
Narrow tools make permissions easier to reason about and reduce the consequences of a bad model decision.
Every tool should have a clear schema. Required fields, enums, ranges, identifiers, and expected formats should be explicit.
The server must validate arguments again after the model produces them.
The MCP client selecting a tool does not prove that the operation is allowed.
The server should authenticate the request, identify the user and agent, verify tenant ownership, check the requested capability, and only then execute it.
Return the smallest useful result. Large database objects waste context and can expose information unrelated to the task.
Use field allowlists for sensitive resources.
Documents, tickets, webpages, and database text may contain instructions designed to manipulate the agent.
MCP servers should return content as data. They should not allow retrieved text to bypass the server's authorization rules.
Tools that create, update, delete, send, publish, or pay should be clearly named and separately permissioned.
High-impact operations may require human approval.
Log tool name, request ID, agent identity, resource scope, latency, result category, and authorization outcome. Never put secrets into model-facing results or normal logs.
A good MCP server is a small, auditable capability layer. Keep tools narrow, validate inputs, enforce permissions server-side, minimize outputs, and make every side effect observable.
Source: MCP architecture and secure tool-design principles.
A practical MCP deployment should keep four boundaries explicit: identity, capability, resource, and execution. Identity answers who is acting. Capability answers which tool is allowed. Resource answers which tenant, project, record, or environment can be touched. Execution controls answer how the operation is performed, including timeouts, retries, quotas, and approval requirements.
Do not rely on tool descriptions to enforce these boundaries. Descriptions help the model choose correctly, but the MCP server or trusted backend must reject unauthorized requests. This also protects the system when a prompt injection, buggy client, or compromised workflow sends an unexpected call.
For external dependencies, use bounded timeouts and classify errors. A temporary provider outage may justify a retry, while an authorization failure should stop immediately. For side effects, make duplicate execution safe with idempotency or an operation-status check before retrying.
Test valid and invalid arguments, missing permissions, cross-tenant resource IDs, revoked credentials, unavailable servers, malformed tool results, rate limits, timeouts, and cancellation. Also test what happens when retrieved content contains instructions that attempt to invoke a privileged operation.
For production systems, include integration tests that verify the full chain from authenticated user to MCP client, server policy, downstream service, and sanitized result. A successful local tool call is not enough evidence that the complete security boundary is correct.
MCP becomes valuable when it makes capabilities composable without making authority ambiguous. Keep discovery selective, permissions deterministic, identity explicit, data minimized, and execution observable.
Choose where policy lives before adding more servers. In a small product, the MCP server itself can own authorization and resource checks. In a larger system, a gateway or policy service can provide shared identity, quotas, and audit decisions while each server retains domain-specific validation. What matters is that there is one trusted enforcement path and that clients cannot bypass it.
Keep development capabilities separate from production capabilities. A developer-facing server may expose logs, database inspection, or test data that should never be discoverable by a customer-facing agent. Use separate credentials, registries, and environments where appropriate.
For long-running workflows, persist the workflow state outside the model. If an MCP server disconnects, the system should be able to resume or fail safely without asking the model to reconstruct critical authorization state from conversation history.
Plan for servers disappearing, credentials expiring, downstream APIs returning malformed data, and clients receiving stale tool definitions. A discovery failure should not silently fall back to a broader capability. A permission failure should not be converted into a generic retry. A timeout should not automatically mean that a side effect did not happen.
Use health checks, bounded retries, circuit breakers for unstable dependencies, and clear degraded states. When a tool becomes unavailable, the agent should know that capability is unavailable rather than inventing a result.
Before production, ask whether every exposed tool has a clear owner, a documented purpose, a resource boundary, a permission model, a timeout, an error contract, and an audit trail. Remove tools that are unused or whose authority cannot be explained precisely.
The goal is not the largest MCP tool catalog. The goal is a small set of capabilities that an agent can use predictably and that engineers can explain during a security review.
Start with one read-only server and a small allowlist of tools. Measure discovery, execution latency, denied calls, errors, and successful task completion. Once the read path is stable, add one carefully scoped write operation with an approval requirement. Only then consider broader integrations.
This staged approach makes failures easier to isolate and keeps the blast radius small. It also creates useful evidence for deciding which tools deserve permanent access. Remove capabilities that provide little value relative to their security and maintenance cost.
Can a tool access a resource outside the current tenant? Can retrieved content influence a privileged operation? Can a retry duplicate a side effect? Can an expired credential remain usable? Can a client discover a production-only capability? Can an error reveal sensitive data? Can one compromised server reach unrelated internal systems?
If any answer is unclear, the integration is not finished. Make the boundary explicit in code, tests, and documentation before expanding the tool set.
Community
0 comments
React to this article
Trending now
Written by
Kirtesh Admute
Founder
Kirtesh Admute is the founder of IndieFounder, a platform for founders, builders, and people curious about technology. He writes about AI, startups, software, product building, and the lessons that come from building in public.
See an issue with this story?
