io.github.kioie/tiny-go-mcp

Official

by kioie · Go

Tiny Go MCP Server

Demo stdio MCP server (tools, resource, prompt) for tinymcp tests—not production use.

Demo MCP server for testing tools, resources, and prompts—not for production use.

Topics

ai-agentscursorgogolangllmmcpmodel-context-protocolclaudemcp-serverlightweightsdk

README.md17 KBView on GitHub

Tiny Go MCP Server

A lightweight Model Context Protocol (MCP) toolkit for Go. Build spec-compliant MCP servers (stdio, streamable HTTP, legacy SSE) with tools, resources, and prompts — minimal boilerplate and automatic JSON Schema from Go structs.

Built on the official modelcontextprotocol/go-sdk.

Requirements: Go 1.26+ (download).

Why Tiny?

	Tiny Go MCP Server	Full frameworks
Goal	Thin helper on official go-sdk + tiny static binary	Full MCP feature surface
Deps	Official go-sdk only	Varies
Binary	~5MB stripped, no runtime on host	Often larger stacks
Schemas	Inferred from struct tags	Manual or builder APIs

Use this project as a library (tinymcp package) or as a starting template (cmd/tiny-go-mcp).

When to use what

	tinymcp (this repo)	mcp-go	go-sdk alone
Best for	Thin helper on go-sdk, tiny binary	Rich helpers, large ecosystem	Full control, no extra layer
Schema	Struct tags → auto JSON Schema	Builder APIs / helpers	`AddTool` + generics yourself
Transport	stdio (`Start()`), streamable HTTP (`StartHTTP`), legacy SSE (`StartSSE`)	stdio, SSE, HTTP, …	All transports
Deps	go-sdk only	Standalone module	go-sdk only

Choose tinymcp when you want the official protocol implementation with minimal boilerplate and a small static server binary.

Philosophy

tinymcp is a thin helper on the official go-sdk — not a replacement for it.

We reduce setup and transport boilerplate (server creation, registration error handling, stdio/HTTP/SSE, TextResult, deploy examples). The protocol implementation, generics, and schema inference still come from modelcontextprotocol/go-sdk.

That means handler code uses both imports — and that is intentional:

import (
    "github.com/kioie/tiny-go-mcp-server/tinymcp"
    "github.com/modelcontextprotocol/go-sdk/mcp" // handler types, prompts, resources, advanced APIs
)

Use tinymcp for	Use go-sdk (`mcp`) for
`NewServer`, `RegisterTool`, transports	Handler signatures (`CallToolRequest`, `GetPromptRequest`, …)
Safe registration (errors, not panics)	Tool annotations, elicitation, custom protocol features
`TextResult`, HTTP middleware helpers	Anything via `server.RawServer()`

We are not aiming for a non-leaky facade that hides the SDK. If you need full control, call RawServer() or use go-sdk directly — same underlying server, no lock-in.

tinymcp vs raw go-sdk

Same protocol implementation — tinymcp removes repetitive setup. Handler code still imports mcp for request types in both cases.

go-sdk alone (minimal stdio server):

server := mcp.NewServer(&mcp.Implementation{Name: "my-mcp", Version: "1.0.0"}, nil)
mcp.AddTool(server, &mcp.Tool{
    Name:        "greet",
    Description: "Greet someone by name",
}, greet)
if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
    log.Fatal(err)
}

tinymcp (same tool, less boilerplate):

s := tinymcp.NewServer("my-mcp", "1.0.0")
if err := tinymcp.RegisterTool(s, "greet", "Greet someone by name", greet); err != nil {
    log.Fatal(err)
}
log.Fatal(s.Start())

tinymcp adds	Still on go-sdk (`mcp`)
`NewServer(name, ver)`	Handler signatures (`CallToolRequest`, prompts, resources)
`RegisterTool` + struct-tag JSON Schema	Tool annotations via `RegisterToolDef` + `mcp.Tool`
Safe registration errors (no panics)	Advanced session / event-store APIs
`Start()` / `StartHTTP()` / HTTP middleware	Full control via `RawServer()`

Use go-sdk alone when you want zero wrapper. Use tinymcp when you want less setup while staying on the official implementation.

Transport

Method	API	Typical clients
stdio (default)	`Start()`	Cursor, Claude Desktop, Windsurf (local subprocess)
Streamable HTTP	`StartHTTP(addr, opts)` or `StreamableHTTPHandler`	Remote MCP clients, gateways, browser tools
Legacy SSE	`StartSSE(addr, opts)` or `SSEHandler`	Older clients on MCP 2024-11-05 SSE transport

Start() runs stdio (stdin/stdout) — what most local AI clients expect.

For HTTP/SSE, tinymcp wraps the official go-sdk handlers with minimal options:

// Streamable HTTP on loopback (stateless demo — no GET/SSE or server→client RPC)
log.Fatal(server.StartHTTP("127.0.0.1:8080", &tinymcp.HTTPOptions{Stateless: true}))

// Or mount on your own mux (auth, TLS, path prefix)
handler, _ := tinymcp.StreamableHTTPHandler(server, nil)
http.Handle("/mcp", handler)

Stateless mode (Stateless: true) is the default in examples: one POST JSON-RPC per request, no long-lived SSE GET stream, and no server-initiated messages. Omit it or use session options when you need full streamable HTTP sessions — see docs/HTTP.md.

See docs/HTTP.md and examples/http. To host for Smithery URL listing (no Docker for end users), use examples/http-deploy. For advanced session routing or event stores, use server.RawServer() with the go-sdk directly.

Quick start (library)

Step-by-step guide: docs/QUICKSTART.md. AI codegen: SYSTEM_PROMPT.md.

bash

go get github.com/kioie/tiny-go-mcp-server/tinymcp@latest

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/kioie/tiny-go-mcp-server/tinymcp"
	"github.com/modelcontextprotocol/go-sdk/mcp"
)

type greetArgs struct {
	Name string `json:"name" jsonschema:"Person to greet"`
}

func main() {
	s := tinymcp.NewServer("my-mcp", "1.0.0")
	if err := tinymcp.RegisterTool(s, "greet", "Greet someone by name", greet); err != nil {
		log.Fatal(err)
	}
	log.Fatal(s.Start())
}

func greet(_ context.Context, _ *mcp.CallToolRequest, args greetArgs) (*mcp.CallToolResult, any, error) {
	return tinymcp.TextResult(fmt.Sprintf("Hello, %s!", args.Name)), nil, nil
}

See examples/minimal for a runnable copy-paste example.

Scaffold a new server

Requires tagged module template/ (v1.1.1+) for stdio, or template-http/ for streamable HTTP:

bash

go install golang.org/x/tools/cmd/gonew@latest
gonew github.com/kioie/tiny-go-mcp-server/template@latest example.com/my-mcp my-mcp
cd my-mcp && go run .

# HTTP deploy (Smithery / Fly / Render):
gonew github.com/kioie/tiny-go-mcp-server/template-http@latest example.com/my-mcp-http my-mcp-http
cd my-mcp-http && go run .

Or copy examples/minimal, template/, or template-http/ directly.

Install the example server

Both install paths produce a binary named tiny-go-mcp:

bash

# Installs to $(go env GOPATH)/bin/tiny-go-mcp
go install github.com/kioie/tiny-go-mcp-server/cmd/tiny-go-mcp@latest

Or build from source (binary in the repo root):

bash

git clone https://github.com/kioie/tiny-go-mcp-server.git
cd tiny-go-mcp-server
make release   # → ./tiny-go-mcp

Method	Binary name	Typical path
`go install …/cmd/tiny-go-mcp`	`tiny-go-mcp`	`$(go env GOPATH)/bin/tiny-go-mcp`
`make build` / `make release`	`tiny-go-mcp`	`./tiny-go-mcp` in the repo
`make install`	`tiny-go-mcp`	`$(go env GOPATH)/bin/tiny-go-mcp`

Example tools (reference server)

These tools exist for MCP integration demos, not production logic. Agents should compute math and write greetings in-chat unless they are explicitly testing tool calls.

Tool	When to use	When not to / alternative	Arguments
`add`	Test that the client can call an addition tool	Real arithmetic → compute locally or use a calculator MCP	`a`, `b`
`subtract`	Test subtraction wiring (use instead of `add` for subtraction tests)	Real arithmetic → compute locally	`a`, `b`
`greet`	Test a text-returning tool (use instead of `add`/`subtract` for messaging demos)	User-facing hello → reply in the conversation	`name` (required), `greeting` (optional)

Connect AI clients

MCP servers communicate over stdio. Point your client at the compiled binary path.

Template config: examples/mcp-client-config.json (copy and set the absolute path to tiny-go-mcp).

Logging: The protocol uses stdin/stdout. Server logs (if any) go to stderr only. Set TINY_GO_MCP_VERBOSE=1 on the server process to enable startup log lines.

Cursor

Settings → Features → MCP → Add server:

Name: tiny-go-mcp
Type: stdio
Command: /absolute/path/to/tiny-go-mcp

Or add to .cursor/mcp.json in your project:

json

{
  "mcpServers": {
    "tiny-go-mcp": {
      "command": "/absolute/path/to/tiny-go-mcp"
    }
  }
}

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

json

{
  "mcpServers": {
    "tiny-go-mcp": {
      "command": "/absolute/path/to/tiny-go-mcp"
    }
  }
}

Windsurf / Zed / other stdio clients

Use the same shape: command = absolute path to tiny-go-mcp, transport = stdio. Refer to your client’s MCP docs for the config file location.

Tips for LLM-friendly tools

Use clear tool names (snake_case) and descriptions that say when to use, when not to, and which sibling tool applies — models pick tools from these and often have overlapping options.
Add jsonschema tags on struct fields so argument docs appear in the schema.
Return human-readable text via tinymcp.TextResult for predictable client display.
See AGENTS.md for conventions when extending this repo with AI assistants.

Resources and prompts

if err := tinymcp.RegisterTextResource(server, "file:///info", "info", "Server metadata", "text/plain", "…"); err != nil {
	log.Fatal(err)
}
if err := tinymcp.RegisterPrompt(server, "code_review", "Review code", []*mcp.PromptArgument{
	{Name: "code", Required: true},
}, func(_ context.Context, req *mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
	code := req.Params.Arguments["code"]
	if code == "" {
		return nil, tinymcp.RequiredPromptArgument("code")
	}
	return tinymcp.PromptResult("Review", tinymcp.UserPromptMessage("Review:\n"+code)), nil
}); err != nil {
	log.Fatal(err)
}

Runnable example: examples/resources. For dynamic URI templates use RegisterResourceTemplate.

Package API

server := tinymcp.NewServer("name", "version")
tinymcp.NewServer("name", "version", tinymcp.WithInstructions("…")) // optional SDK config
tinymcp.NewServerWithOptions("name", "version", &mcp.ServerOptions{…})
tinymcp.RegisterTool(server, name, description, handler)     // typed handler, auto schema
tinymcp.RegisterTextResource(server, uri, name, desc, mime, text)
tinymcp.RegisterPrompt(server, name, desc, args, handler)
server.Start()                                              // stdio transport
server.StartHTTP(":8080", &tinymcp.HTTPOptions{})         // streamable HTTP
server.StartSSE(":8080", nil)                             // legacy SSE
tinymcp.StreamableHTTPHandler(server, nil)                // mount on custom http.Server
tinymcp.TextResult("message")                               // tool text helper
tinymcp.TextResource(uri, mime, text)                       // resource read helper
tinymcp.PromptResult(desc, tinymcp.UserPromptMessage("…")) // prompt helper
server.RawServer()                                          // escape hatch to go-sdk

// v1.2+: panic-at-startup registration or errors.Is sentinels
tinymcp.MustRegisterTool(server, name, description, handler)
errors.Is(err, tinymcp.ErrNilServer)                        // ErrNilTool, ErrNilHandler, ErrRegistrationFailed
opts := (&tinymcp.HTTPOptions{Stateless: true}).WithMiddleware(requestLogger)
tinymcp.ListenAndServeHTTPContext(ctx, addr, handler)       // graceful shutdown; also StartHTTPContext / StartSSEContext

Documentation: pkg.go.dev/github.com/kioie/tiny-go-mcp-server/tinymcp. Upgrading from v1.1.x: docs/MIGRATION-v1.2.md.

Development

Command	Description
`make test`	Run tests with race detector
`make lint`	golangci-lint
`make lint-tools`	Validate MCP tool descriptions in reference servers
`make coverage`	Coverage report
`make build`	Dev binary `./tiny-go-mcp`
`make release`	Stripped static binary
`make install`	`go install` → `$(go env GOPATH)/bin/tiny-go-mcp`

Smaller binaries (~1.8MB)

After make release, optionally pack with UPX:

bash

upx --best --lzma tiny-go-mcp

Project structure

code

tinymcp/              # Library package
cmd/tiny-go-mcp/      # Reference MCP server
template/             # gonew stdio scaffold
template-http/        # gonew streamable HTTP deploy scaffold
examples/minimal/     # Minimal stdio example
examples/http/        # Streamable HTTP example
examples/http-deploy/ # Deployable HTTP + Smithery URL listing (server card, Render/Fly)
examples/resources/   # Resources + prompts example
examples/mcp-client-config.json  # Cursor/Claude-style template
scripts/lint-tools/   # MCP tool description linter (make lint-tools)
docs/                 # Guides — see below
server.json           # MCP Registry metadata (publish with mcp-publisher)
CHANGELOG.md          # Release history
SYSTEM_PROMPT.md      # Agent-facing API summary for codegen
.github/workflows/    # CI, lint, CodeQL, releases

Key docs in docs/:

Doc	Purpose
QUICKSTART.md	Step-by-step library setup
HTTP.md	stdio vs streamable HTTP vs legacy SSE
STABILITY.md	Public API stability policy
MIGRATION-v1.2.md	Upgrade guide from v1.1.x
TLS.md	HTTPS via reverse proxy or Go
LOCALHOST-PROTECTION.md	DNS rebinding security advisory
DISCOVERY.md	Registries and visibility
GLAMA.md	Glama hosting
SMITHERY.md	Smithery URL and MCPB listings

Releases

Tag a semver version (e.g. v1.2.0) to publish stable go get versions and trigger GitHub Releases with cross-platform binaries and multi-arch GHCR images. Release history: CHANGELOG.md. Public API stability: docs/STABILITY.md. Agent-facing API summary: SYSTEM_PROMPT.md. Upgrading from v1.1.x: docs/MIGRATION-v1.2.md.

bash

git tag v1.2.0
git push origin v1.2.0

Discovery and registries

See docs/DISCOVERY.md for MCP Registry (server.json), awesome lists, and community directories. Listing copy and launch posts: docs/SUBMISSIONS.md. For Glama hosting with Docker, see docs/GLAMA.md.

Contributing

See CONTRIBUTING.md. For AI codegen outside this repo, see SYSTEM_PROMPT.md. CI runs tests, lint, and CodeQL; Dependabot keeps Go and Actions dependencies updated.

License

MIT — see LICENSE.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "tiny-go-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/kioie/tiny-go-mcp:1.1.2"
      ]
    }
  }
}