# Go MCP servers

Read [../mcp.md](../mcp.md), [baseline.md](baseline.md), [mise.md](mise.md),
[cli.md](cli.md), and [preferred-libraries.md](preferred-libraries.md) before
applying these Go MCP specifics.

Use the official Go SDK: `github.com/modelcontextprotocol/go-sdk`. Default to
stdio for local agent use; choose Streamable HTTP only when the server needs
networked clients or deployment behind an HTTP boundary.

MCP servers are still command-line binaries. Keep the CLI/versioning rules from
[cli.md](cli.md) in force.

## Shape

```text
cmd/<server>/main.go       # CLI entrypoint
cmd/<server>/serve.go      # serve command and transport flag
internal/config/config.go  # env and flag parsing
internal/server/server.go  # MCP implementation, transports, handlers
internal/server/tools.go   # typed tool parameter structs, split into tool-per-file if it gets unwieldy
internal/<client>/...      # API client being wrapped
```

## Tools

- Use typed parameter structs with JSON and jsonschema tags.
- 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 MCP `IsError` for tool-level
  domain errors the model should see.
- Clamp or validate bounds at the boundary and document whether clamping is
  silent or an error.

If the wrapped API has sharp edges, add a `usage`/instructions tool documenting
them.

## Config

- 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.

## Release

MCP servers are usually plain static binaries. Use `CGO_ENABLED=0` unless a
dependency requires CGO. Add nFPM only when system installation, services, or
managed config files are part of the product.

Prefer the static build shape from [mise.md](mise.md): `netgo`, `osusergo`,
optional project-specific `static_build`, `-d -s -w -buildid= -extldflags=-static`,
and explicit version injection when the server exposes `--version` or embeds
version metadata. Do not rely on Fang's CLI fallback alone for MCP implementation
metadata; use the same project-owned version value anywhere the server reports
it. Remove those static-only pieces when the wrapped API client or storage layer
requires CGO.