template-mcp

template-mcp is a Go template for building Model Context Protocol (MCP) servers. It is built on the official modelcontextprotocol/go-sdk and ships with the protocol and security best practices that an MCP server should have on day one.

The template exposes a single demo tool, random_int, and demonstrates serving it over two transports from the same server code:

• Local — the STDIO transport (template-mcp stdio), which clients spawn as a subprocess.
• Networked — the Streamable HTTP transport (template-mcp http), suitable for remote and containerized deployments.

Generated projects keep the transport they need and delete the other (see Choosing a transport).

Local Bootstrap

Prerequisites:

• Go 1.26.4
• Moon 2.x
• Python 3.14.3 and uv 0.11.0 for the MkDocs documentation project

After creating a new repository from this template, replace the placeholder names before doing feature work:

go mod edit -module github.com/meigma/YOUR_REPO
mv cmd/template-mcp cmd/YOUR_BINARY

Then update template-mcp references in the Moon tasks, GoReleaser config, ghd.toml, README, and package docs. The full first-setup checklist lives in DELETE_ME.md.

Running the Server

Run the server over STDIO (the mode a local MCP client launches):

go run ./cmd/template-mcp stdio

Run the server over Streamable HTTP, bound to loopback by default:

go run ./cmd/template-mcp http --addr localhost:8080

Both subcommands build the same internal/mcpserver server and differ only in how they connect it to a transport.

Hot Reload During Development

The repository ships a dev proxy (tools/proxy) and a checked-in .mcp.json that wires it up, so developing the server with Claude Code needs no setup. Start claude in the repository root, approve the project-scoped dev server, and edit the server source: the proxy rebuilds on save and swaps the running server behind the live session — new and changed tools appear on the next conversation turn with no reconnect. See tools/proxy/README.md for how it works and its flags.

The Demo Tool

The template registers one tool, random_int, in internal/mcpserver. It takes min and max arguments and returns a uniformly random integer in the inclusive range [min, max].

The tool is deliberately small but exercises the parts of the protocol you are most likely to use:

• Typed input and output structs, from which the SDK derives the JSON Schemas automatically.
• Structured output, marshaled from the typed return value by the SDK.
• The tool-error convention: an invalid range (min > max) returns a tool-level error result (IsError) rather than a JSON-RPC protocol error.

Replace random_int with your own tool, or add more tools alongside it. The server and transport code do not change when you do.

Choosing a Transport

The server in internal/mcpserver knows nothing about transports. Each transport is a Cobra subcommand in its own file:

• internal/cli/stdio.go — the stdio subcommand.
• internal/cli/http.go — the http subcommand.

To keep only one transport, delete the unused file and remove its single registration line in internal/cli/root.go. The tool and server code are untouched.

Security & Best Practices

The template bakes in the practices that an MCP server must have. Preserve them as you build on it.

• stdout is reserved for JSON-RPC. Over the STDIO transport, stdout carries protocol messages only. Writing anything else to stdout — a stray fmt.Println, a logger pointed at os.Stdout — silently corrupts the stream and is the most common way a stdio server breaks. The template logs to os.Stderr only; keep all logging and diagnostics on stderr.
• Origin verification and a loopback default for HTTP. The http transport wraps the SDK handler in the standard library's cross-origin protection to defend against DNS-rebinding and CSRF from browsers, and --addr defaults to localhost:8080. Binding to a non-loopback address exposes the server to the network and is an explicit, security-relevant decision.
• The HTTP transport fails closed off loopback. Cross-origin protection stops malicious browsers, not direct clients such as curl. So binding a non-loopback address (for example 0.0.0.0) with no authentication is refused at startup unless you either set --auth-token or pass --insecure to opt into an unauthenticated, network-exposed server. The container image defaults to --insecure so the demo runs out of the box; remove it and supply real authentication before deploying.
• The bearer-auth seam is demo-only. The HTTP transport includes a minimal, flag-gated bearer-token check that is off by default and exists to show where authorization belongs. It is not production authorization. A production server needs a real OAuth 2.1 resource server: protected-resource metadata (RFC 9728), audience-restricted tokens (RFC 8707), and PKCE with S256. Validate token signature, expiry, and audience against a trusted authorization server.
• Authorization is HTTP-only. Per the MCP specification, authorization applies to HTTP transports only. STDIO servers must not use OAuth; they take any credentials they need from the environment of the process that launched them.

Common Tasks

Moon is the standard task front door:

moon run root:format
moon run root:lint
moon run root:build
moon run root:test
moon run root:check

CI runs the same aggregate check:

moon ci --summary minimal

The CLI entrypoint uses Cobra and Viper in the same shape as other Meigma CLIs: cmd/template-mcp stays thin, internal/cli owns command construction, and Viper-backed flags such as the HTTP address can also be supplied through TEMPLATE_MCP_* environment variables.

go run ./cmd/template-mcp --version
go run ./cmd/template-mcp stdio
go run ./cmd/template-mcp http --addr localhost:8080
go test ./...

Container Image

The included Dockerfile builds a static Linux binary and copies it into a non-root distroless runtime image:

docker build --target test .
docker build -t template-mcp:dev .
docker run --rm template-mcp:dev --version

The Dockerfile pins the builder and runtime images by digest and verifies that the selected Go builder image matches .go-version. When bumping Go, update .go-version and the builder FROM tag/digest together.

Containers are the networked deployment, so a container most likely runs the http subcommand. The image defaults to http --addr 0.0.0.0:8080 --insecure, which runs the demo unauthenticated; --insecure is required because the server otherwise refuses to bind a non-loopback address without authentication. Before deploying, drop --insecure and supply real authorization (see the security expectations above).

Release builds can pass the same binary metadata injected by GoReleaser:

docker build \
  --build-arg VERSION="$(git describe --tags --always --dirty)" \
  --build-arg COMMIT="$(git rev-parse HEAD)" \
  --build-arg DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -t template-mcp:dev .

CI and Security

The default CI workflow keeps permissions minimal, pins external actions, disables checkout credential persistence, and delegates checks to Moon. It uses GitHub-hosted dependency caches for Go, golangci-lint, and uv download artifacts while leaving Moon remote caching as an optional follow-up for repositories that need a shared task-output cache. The docs workflow builds the MkDocs site on pull requests and deploys docs/build to GitHub Pages from the default branch. The scheduled security scan workflow builds the local container image weekly, scans it for high/critical fixed vulnerabilities, and uploads SARIF results to GitHub code scanning. Dependabot covers GitHub Actions, Docker base images, the root Go module, and the docs uv project.

Repository settings live in .github/repository-settings.toml. They default to immutable releases, private vulnerability reporting, signed commits, squash-only merges, GitHub Pages workflow publishing, and protected tags.

Release Layer

Release automation is enabled for the template application so this repository proves the full binary and container release lifecycle before generated projects inherit it. Repositories generated from the template should update the release app credentials, package names, asset patterns, container image name, and ghd.toml signer workflow before cutting their first release.

The release path is:

• Release Please opens and maintains the release PR.
• Release Please creates a draft GitHub release and tag after merge.
• Release Dry Run rehearses the GoReleaser binary path and native-runner Docker container build path on pull requests.
• GoReleaser builds binaries, checksums, and SBOMs without publishing directly.
• The release workflow uploads assets to the draft release and creates a GitHub-hosted attestation for checksums.txt.
• The release workflow builds amd64 and arm64 container images on native GitHub-hosted runners, publishes ghcr.io/meigma/template-mcp:vX.Y.Z as a multi-platform manifest, attaches BuildKit provenance and SBOM metadata, and creates a GitHub-native attestation for the manifest digest.
• A human inspects the draft release before publication.

The root ghd.toml matches the default GoReleaser output so generated projects can be installed with ghd once the release workflow runs. After cloning this template, update provenance.signer_workflow, package names, asset patterns, binary paths, and image names to match the new repository and binary name.

Contributing

See CONTRIBUTING.md for contribution guidelines, local setup expectations, and pull request workflow.

Security

See SECURITY.md for supported versions and the private vulnerability reporting path.

License

Add the repository license before publishing a project generated from this template.