Mcp server

MCP server

The Model Context Protocol lets an agent discover and call your tools and read your resources. The server is a contract with a caller that reasons in natural language and will misuse anything ambiguous, so design for a smart caller that cannot see your source.

Method

1. Expose the right primitive. MCP offers tools (actions the agent invokes), resources (data the agent reads), and prompts (templates the agent fills). Read-only data is a resource, not a tool; an action with effects is a tool. Choosing wrong makes the agent fetch data by calling side-effecting tools, or take actions it thinks are safe reads.
2. Name and describe for the model, not the maintainer. Every tool's name and description is how the agent decides whether and how to call it. Say what it does, when to use it, and what it returns, in one clear statement. A vague description produces wrong calls no schema can prevent.
3. Make schemas strict and self-documenting. Each parameter has a type, a description, and required-or-optional stated. Constrain enums, ranges, and formats so the model cannot pass a shape you will reject. Invalid states the schema forbids are calls you never have to handle.
4. Return results the model can use. Structured, labeled output over raw dumps; the fields the agent needs to decide the next step, not your internal representation. Truncate or paginate large results so one call cannot blow the context window.
5. Errors are part of the contract. A failed call returns a clear, actionable message the agent can recover from ("file not found: check the path" beats a stack trace). Distinguish the agent's mistake from a server failure so the agent knows whether to retry, fix its input, or give up.
6. Guard every boundary, because the caller is not trusted. Validate and sanitize all inputs; scope what each tool can touch; never expose a tool that runs arbitrary commands, reads arbitrary paths, or leaks secrets. Treat tool arguments as hostile input reaching a privileged operation, because that is exactly what they are.
7. Keep tools small and composable. One tool, one job, with a name that says it. A mega-tool with a mode parameter is harder for the agent to use correctly than three focused tools.

Litmus tests

• Could the agent use every tool correctly from its name, description, and schema alone, with no access to your code?
• Can any tool call cause damage the caller did not clearly intend?
• Does every error tell the agent what to do next?
• Could a single response overflow the context window?

Boundaries

Follow the MCP specification and your SDK's conventions; a server that diverges from the protocol is a server clients cannot use. Expose the smallest surface that serves the need. Every tool is attack surface and context cost, so a tool that is rarely useful is a net loss.