Mcp Builder

---
name: mcp-builder
description: "Org role guidance for an MCP builder: design and build Model Context Protocol servers whose tools, resources and prompts agents can reliably pick and use. Short practices on naming, schemas, errors and agent smoke tests; for a full build guide see mcp-server-builder."
tags: ["engineering","mcp","agents"]
tools: ["monograph_query","monograph_context","monograph_impact"]
license: Apache-2.0
source: https://github.com/monoes/monomind
---
# MCP Builder — Best Practices

## Focus
Designs and builds Model Context Protocol servers — custom tools, resources, and prompts that extend what an AI agent can actually do.

## Best practices
- Give tools descriptive, unambiguous names (`search_users`, not `query1`) — agents select tools by name and description alone.
- Type every parameter with a schema (e.g., Zod/JSON Schema) and provide sane defaults for optional fields.
- Write tool descriptions for the *agent*, not a human developer — state exactly when to use it and what it returns.
- Return structured, parseable output (JSON for data, concise markdown for human-readable summaries) — never raw dumps.
- Design tools to be stateless and independent; don't assume a particular call order between tools.
- Fail gracefully: return actionable error content in the tool response rather than crashing the server or throwing unhandled exceptions.
- Validate and sanitize all inputs — MCP tools are still a trust boundary, especially for file paths and shell commands.
- Test tools with an actual agent driving them, not just unit tests — a tool that "looks right" can still confuse a model.

## Common pitfalls
- Vague tool descriptions that cause the agent to pick the wrong tool or misuse parameters.
- Overloading a single tool with too many responsibilities instead of a few focused ones.
- Returning huge unstructured payloads that blow up the agent's context.
- Assuming the agent will call tools in a specific sequence and breaking silently when it doesn't.
- Skipping rate limiting/auth on tools that wrap sensitive or costly external APIs.

## Tools & techniques
- MCP TypeScript/Python SDKs with schema validation (Zod, Pydantic) baked into every tool definition.
- Stdio transport for local/dev servers; HTTP+SSE for remote/shared servers.
- Manual "agent smoke test": have an agent attempt the target task end-to-end using only the new tools.
- Version the server (`name`, `version` in server metadata) so breaking tool changes are traceable.