MCP Server Template (Go)

A production-ready template for building Model Context Protocol (MCP) servers in Go, following official best practices and guidelines.

Features

• Complete MCP Implementation - Tools, Resources, and Prompts
• Production-Ready - Graceful shutdown, signal handling, and error handling
• Well-Tested - Unit and integration tests with examples
• Configurable - YAML-based configuration with validation
• Secure - Input validation, sanitization, and best practices
• Docker Support - Ready for containerized deployments
• Best Practices - Follows the official MCP implementation guide

Quick Start

Prerequisites

• Go 1.23 or higher
• Make (optional, for using Makefile commands)

Installation

1. Clone or use this template:

   git clone <your-repo-url>
   cd mcp-server-template
   

2. Install dependencies:

   go mod download
   

3. 🚨 IMPORTANT: Clean up template examples

   This template includes example tools, resources, and prompts. You should remove these before starting your project.

   See CLAUDE.md for detailed instructions on:

   • What files to remove
   • How to clean up register functions
   • How to update configuration
   • How to customize CLAUDE.md for your project

   Quick cleanup:

   # Remove example implementations
   rm internal/tools/{search,calculate,analyze}.go
   rm internal/tools/{search,calculate,analyze}_test.go
   rm internal/resources/files.go internal/resources/files_test.go
   rm internal/prompts/greet.go internal/prompts/greet_test.go
   rm tests/integration/server_test.go tests/testdata/fixtures.json
   

4. Configure the server:

   # Edit configs/config.yaml to customize
   nano configs/config.yaml
   

5. Build and run:

   make build
   make serve
   

   Or directly:

   go run ./cmd/server serve
   

Usage

This server provides two interfaces: MCP server mode for integration with MCP clients, and CLI tool mode for direct command-line execution.

As MCP Server

Run as an MCP server using stdio transport for integration with MCP clients (like Claude Desktop):

# Using make
make serve

# Or directly
./bin/server serve

The server will run in the foreground and communicate via stdin/stdout. Press Ctrl+C for graceful shutdown.

As CLI Tool

Execute tools directly from the command line:

# Get help
./bin/server --help
./bin/server --version

# Get help for a specific command
./bin/server search --help

# Execute tools (examples - replace with your actual tools)
./bin/server search --query "golang testing" --limit 5
./bin/server calculate --operation add --a 10 --b 20

# Different output formats
./bin/server search --query "golang" --output json
./bin/server search --query "golang" --output yaml
./bin/server search --query "golang" --output text  # default

# Quiet mode (exit code only, no output)
./bin/server search --query "golang" --quiet
echo $?  # Check exit code

Note: The example commands above assume you have implemented tools like search and calculate. Adjust the commands based on your actual tool implementations.

Configuration

Both MCP server mode and CLI tool mode use the same configuration file:

# Use default config (configs/config.yaml)
./bin/server serve

# Use custom config
./bin/server --config /path/to/config.yaml serve
./bin/server --config /path/to/config.yaml search --query "test"

Project Structure

mcp-server-template/
├── cmd/
│   └── server/
│       └── main.go              # Entry point with graceful shutdown
├── internal/
│   ├── tools/                   # MCP tools (one per file)
│   │   ├── register.go          # Tool registration
│   │   ├── search.go            # Search tool
│   │   ├── search_test.go       # Search tests (same package)
│   │   ├── calculate.go         # Calculate tool
│   │   ├── calculate_test.go    # Calculate tests
│   │   ├── analyze.go           # Analyze tool
│   │   └── analyze_test.go      # Analyze tests
│   ├── resources/               # MCP resources
│   │   ├── register.go          # Resource registration
│   │   ├── files.go             # File system resources
│   │   └── files_test.go        # File tests
│   ├── prompts/                 # MCP prompts
│   │   ├── register.go          # Prompt registration
│   │   ├── greet.go             # Greeting prompt
│   │   └── greet_test.go        # Greeting tests
│   ├── config/                  # Configuration management
│   │   ├── config.go            # Config loading and validation
│   │   └── config_test.go       # Config tests
│   └── services/                # Business logic (add your services here)
├── tests/
│   ├── integration/             # Integration tests
│   │   └── server_test.go       # Full server tests
│   └── testdata/                # Test fixtures
│       └── fixtures.json
├── configs/
│   └── config.yaml              # Server configuration
├── docs/
│   └── MCP_SERVER_IMPLEMENTATION_GUIDE.md  # Complete implementation guide
├── go.mod                       # Go module definition
├── go.sum                       # Dependency checksums
├── Makefile                     # Build automation
├── Dockerfile                   # Container image
├── README.md                    # This file
└── CLAUDE.md                    # Instructions for Claude Code

Included Examples

Tools

1. search - Search for information with configurable limits
2. calculate - Perform arithmetic operations (add, subtract, multiply, divide)
3. analyze - Analyze text using various methods (sentiment, keywords, summary)

Resources

1. File System - Access local files via file:/// URIs

Prompts

1. greet - Generate personalized greetings with different styles

Configuration

Edit configs/config.yaml:

server:
  name: "your-server-name"
  version: "1.0.0"
  port: 8080

features:
  enable_tools: true
  enable_resources: true
  enable_prompts: true

environment: "dev"  # dev, staging, production

tools:
  search_enabled: true
  analyze_enabled: true
  calculate_enabled: true

Using Environment Variables

For secrets and sensitive data, use environment variables:

# configs/config.yaml
database:
  password: ${DB_PASSWORD}

api:
  api_key: ${API_KEY}

Then set them before running:

export DB_PASSWORD="your-password"
export API_KEY="your-api-key"
./bin/server

Development

Running Tests

# All tests with coverage
make test

# Unit tests only
make test-unit

# Integration tests only
make test-integration

# Generate coverage report
make coverage

Building

# Build binary
make build

# Run locally
make run

# Clean build artifacts
make clean

Code Quality

# Format code
make fmt

# Run linters (requires golangci-lint)
make lint

Docker

# Build image
make docker-build

# Run container
make docker-run

Adding New Features

Adding a New Tool

1. Create internal/tools/mytool.go:

package tools

import (
    "context"
    "fmt"
    "github.com/modelcontextprotocol/go-sdk/mcp"
)

type MyToolInput struct {
    Query string `json:"query" jsonschema:"required,description=Your query"`
}

type MyToolOutput struct {
    Result string `json:"result" jsonschema:"description=The result"`
}

func registerMyTool(server *mcp.Server) {
    mcp.AddTool(server, &mcp.Tool{
        Name:        "mytool",
        Description: "Description of what your tool does",
    }, myToolHandler)
}

func myToolHandler(ctx context.Context, req *mcp.CallToolRequest, input MyToolInput) (
    *mcp.CallToolResult, MyToolOutput, error,
) {
    // Validate inputs
    if input.Query == "" {
        return nil, MyToolOutput{}, fmt.Errorf("query is required")
    }

    // Check context cancellation
    select {
    case <-ctx.Done():
        return nil, MyToolOutput{}, ctx.Err()
    default:
    }

    // Your implementation here
    result := processQuery(input.Query)

    return nil, MyToolOutput{Result: result}, nil
}

1. Create internal/tools/mytool_test.go (in same package)

2. Update internal/tools/register.go:

func Register(server *mcp.Server, cfg *config.Config) {
    // ...
    registerMyTool(server)
}

1. Add config option in configs/config.yaml:

tools:
  mytool_enabled: true

1. Run tests:

make test

Adding Resources or Prompts

Follow the same pattern in internal/resources/ or internal/prompts/.

Testing

This template includes comprehensive tests:

• Unit Tests - Test individual functions and handlers
• Integration Tests - Test the full server with all features
• Table-Driven Tests - Easy to add new test cases
• Error Testing - Verify error handling
• Context Testing - Verify context cancellation

Run tests before committing:

make test

Deployment

Stdio Transport (Default)

The template uses stdio transport by default, suitable for:

• CLI tools
• Local integrations
• Subprocess communication

HTTP Transport

To use HTTP transport, modify cmd/server/main.go:

// Change from stdio to HTTP
handler := mcp.NewStreamableHTTPHandler(
    func(r *http.Request) *mcp.Server { return server },
    nil,
)
log.Fatal(http.ListenAndServe(":8080", handler))

Docker Deployment

# Build image
docker build -t your-server:latest .

# Run container (stdio)
docker run -i your-server:latest

# Run container (HTTP)
docker run -p 8080:8080 your-server:latest

Security Best Practices

This template follows security best practices:

• ✅ Input validation on all tools
• ✅ File path sanitization
• ✅ Parameterized queries (when using databases)
• ✅ Context cancellation support
• ✅ Error wrapping with context
• ✅ No hardcoded secrets
• ✅ Non-root user in Docker

Always:

• Validate and sanitize all inputs
• Use parameterized queries for SQL
• Never commit secrets to version control
• Use environment variables for sensitive data

Customization

Renaming the Module

1. Update go.mod:

   module your-module-name
   

2. Update imports in all files:

   import "your-module-name/internal/config"
   

3. Run:

   go mod tidy
   

Removing Example Features

To remove example tools/resources/prompts:

1. Delete the corresponding files from internal/
2. Update register.go files
3. Update configs/config.yaml
4. Run tests to verify

Documentation

• Implementation Guide: See docs/MCP_SERVER_IMPLEMENTATION_GUIDE.md for comprehensive guidelines
• MCP Specification: https://modelcontextprotocol.io/specification
• Go SDK Documentation: https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk

Contributing

Contributions are welcome! Please:

1. Follow the existing code structure
2. Add tests for new features
3. Update documentation
4. Run make test and make lint before submitting

Architecture Principles

This template follows strict architectural principles:

• ONE tool per file - Maintainability and clarity
• Register pattern - Centralized feature registration
• Unexported handlers - Clean public API
• Same-package unit tests - Access to internals
• Separate integration tests - End-to-end testing
• Configuration-driven - No hardcoded values
• Context-aware - Proper cancellation support
• Error wrapping - Complete error context

See CLAUDE.md for detailed architectural guidelines.

License

[Your License Here]

Support

For questions or issues:

• Check the implementation guide in docs/
• Review example code in internal/
• Open an issue on GitHub

Acknowledgments

Built following the official MCP Go SDK and implementation guidelines.