1# MCP servers
 2
 3Build MCP servers as small, explicit adapters around a domain or external API.
 4Default to stdio for local agent use; choose Streamable HTTP only when the server
 5needs networked clients or deployment behind an HTTP boundary.
 6
 7## Shape
 8
 9- Keep transport/config setup separate from tool handlers.
10- Keep API clients or domain logic outside the MCP layer.
11- Prefer typed parameter/result structures when the language supports them.
12- If the wrapped API has sharp edges, add a `usage`/instructions tool documenting
13  them.
14
15## Tools
16
17- Add tool annotations: read-only/destructive/idempotent/open-world hints.
18- Make descriptions operational: what the tool does, when to use it, and any
19  required prerequisite tool.
20- Return structured errors for real failures. Use tool-level errors for domain
21  failures the model should see and potentially recover from.
22- Clamp or validate bounds at the boundary and document whether clamping is
23  silent or an error.
24
25## Config and release
26
27- Required connection info comes from env vars and/or explicit flags.
28- Validate URLs and auth shape before starting the server.
29- Allow separate auth layers when real deployments need them, but document how
30  headers/cookies interact.
31- Treat MCP servers as installable command-line binaries unless the deployment
32  model clearly says otherwise; read [cli.md](cli.md) and [packaging.md](packaging.md)
33  when building release artifacts.
34
35## Go path
36
37For Go MCP servers, read [golang/index.md](golang/index.md) first and follow its
38MCP chain. That route intentionally loads Go baseline, CLI, mise, and preferred
39library context before `golang/mcp.md`.