Skip to content

Getting started

This tutorial takes you from a fresh clone to a running MCP server over both transports. It assumes nothing beyond a terminal.

Install prerequisites

The toolchain is provisioned by proto and orchestrated by Moon. Install both, then let proto install the pinned Go and lint toolchains:

# Install proto (which can also manage moon and the Go toolchain).
curl -fsSL https://moonrepo.dev/install/proto.sh | bash

# Install moon.
proto install moon

# From the repository root: provision the pinned tools (Go, golangci-lint, moon).
proto install

Building the documentation also needs Python and uv; proto installs both from the pinned versions when you run the docs tasks.

Run over STDIO

The STDIO transport is what a local MCP client launches as a subprocess:

go run ./cmd/template-mcp stdio

The process speaks newline-delimited JSON-RPC over stdin/stdout and blocks until the client closes the input stream or the process is signaled. That is expected: it is a server, not a one-shot command. Diagnostics go to stderr; stdout carries only protocol messages.

Run over Streamable HTTP

The HTTP transport suits networked or containerized deployments. It binds loopback by default:

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

You will see a listening log line on stderr. Press Ctrl-C for a graceful shutdown.

Call the demo tool

Both transports serve the same server, which registers one tool, random_int. It takes min and max and returns a uniformly random integer in the inclusive range [min, max], or a tool-level error if min > max. Point your MCP client at the server and call random_int to see structured output.

Run the checks

Moon is the task front door:

moon run root:build
moon run root:test
moon run root:check   # format, lint, build, test, docs build, and the proxy checks

Next steps