MCP servers

Build MCP servers as small, explicit adapters around a domain or external API. Default to stdio for local agent use; choose Streamable HTTP only when the server needs networked clients or deployment behind an HTTP boundary.

Shape

• Keep transport/config setup separate from tool handlers.
• Keep API clients or domain logic outside the MCP layer.
• Prefer typed parameter/result structures when the language supports them.
• If the wrapped API has sharp edges, add a usage/instructions tool documenting them.

Tools

• Add tool annotations: read-only/destructive/idempotent/open-world hints.
• Make descriptions operational: what the tool does, when to use it, and any required prerequisite tool.
• Return structured errors for real failures. Use tool-level errors for domain failures the model should see and potentially recover from.
• Clamp or validate bounds at the boundary and document whether clamping is silent or an error.

Config and release

• Required connection info comes from env vars and/or explicit flags.
• Validate URLs and auth shape before starting the server.
• Allow separate auth layers when real deployments need them, but document how headers/cookies interact.
• Treat MCP servers as installable command-line binaries unless the deployment model clearly says otherwise; read cli.md and packaging.md when building release artifacts.

Go path

For Go MCP servers, read golang/index.md first and follow its MCP chain. That route intentionally loads Go baseline, CLI, mise, and preferred library context before golang/mcp.md.