Designing MCP Servers That Agents Can Use Reliably
How to structure MCP tools, resources, and auth so agents discover and call them correctly in production.
The Model Context Protocol (MCP) gives agents a standard way to discover tools and resources. A well-designed MCP server feels like a clean API surface for language models: clear names, tight schemas, predictable errors. A poorly designed one becomes a maze of ambiguous tools that agents misuse.
Design for Discovery First
Agents choose tools from descriptions. Optimize for selection:
- Verb-led names —
create_invoice,search_customers, notinvoiceHandler - When-to-use guidance — include positive and negative examples in descriptions
- One job per tool — avoid mega-tools with a
modeenum that agents guess wrong - Stable identifiers — prefer IDs over free-text names in required parameters
Tool: create_refund
Use when a customer requests money back for a completed order.
Do NOT use for store credit or order cancellation.
Parameters:
order_id (string, required)
amount_cents (integer, required)
reason (string, required)
Keep Schemas Strict and Small
Large optional parameter bags invite hallucinated fields. Prefer:
- Required fields that uniquely identify the resource
- Enums over free strings for status and type fields
- Nested objects only when the model must fill structured data
Validate on the server. Never trust the model to send perfect JSON—even with schemas.
Separate Read and Write Surfaces
Split tools by risk:
- Read tools — search, get, list (autonomous)
- Write tools — create, update, delete (often HITL in Meebly)
- Preview tools — dry-run or quote endpoints that return what a write would do
Agents (and humans reviewing approvals) reason better when "preview refund" and "execute refund" are distinct Actions.
Resources vs. Tools
Use MCP resources for reference material the agent should retrieve (policies, catalogs, schemas). Use tools for side effects and parameterized queries. Stuffing long static documents into every tool description wastes context and goes stale; expose them as resources the agent can fetch when needed.
Auth and Tenancy
MCP servers that call customer backends must forward the right credentials. Common patterns:
- OAuth access tokens obtained for the end user
- Session tokens from your app's logged-in context
- Embed tokens scoped to a widget session
- Service credentials only for non-user, system-level operations
Scope tools to the tenant implied by those credentials. An agent should never be able to pass another customer's ID and succeed because the server ignored auth context.
Error Contracts Agents Can Recover From
Return structured, actionable errors:
{
"ok": false,
"code": "ORDER_NOT_REFUNDABLE",
"message": "Order was already refunded",
"hint": "Use get_order to confirm status, then offer store credit"
}
Ambiguous 500s force the agent to retry blindly. Clear codes let system instructions define recovery paths.
Observability Hooks
Emit enough metadata for Traces and Tool Monitoring:
- Tool name and latency
- Error codes (not full PII payloads)
- Auth scheme used (OAuth, session, embed)—not the secret itself
When an MCP server is connected to a Meebly Environment, those signals help you see whether failures are model selection issues or backend issues.
Versioning MCP Surfaces
Breaking tool renames break agents that learned the old names. Prefer additive changes, deprecate with description warnings, and promote MCP server versions alongside Environment promotions.
Conclusion
MCP servers are part of your agent architecture, not just adapters. Design tools for discovery, keep schemas tight, separate reads from writes, forward real credentials safely, and return errors agents can act on. Connected to Meebly Apps and Environments, a good MCP server becomes a governed Action surface—not an unsupervised backdoor into your systems.
