A starter repo for building a go MCP server
Documentation
MCP Go Starter
A feature-complete Model Context Protocol (MCP) server template in Go using the official go-sdk. This starter demonstrates all major MCP features with clean, idiomatic Go code.
📚 Documentation
✨ Features
| Category | Feature | Description |
|---|---|---|
| Tools | hello | Basic tool with annotations |
get_weather | Tool returning structured data | |
ask_llm | Tool that invokes LLM sampling | |
long_task | Tool with 5-second progress updates | |
load_bonus_tool | Dynamically loads a new tool | |
| Resources | info://about | Static informational resource |
file://example.md | File-based markdown resource | |
| Templates | greeting://{name} | Personalized greeting |
data://items/{id} | Data lookup by ID | |
| Prompts | greet | Greeting in various styles |
code_review | Code review with focus areas |
🚀 Quick Start
Prerequisites
- Go 1.22+
- (Optional) air for live reload
- (Optional) golangci-lint for linting
Installation
# Clone the repository
git clone https://github.com/SamMorrowDrums/mcp-go-starter.git
cd mcp-go-starter
# Download dependencies
go mod downloadRunning the Server
stdio transport (for local development):
go run ./cmd/stdio
# Or: make run-stdioHTTP transport (for remote/web deployment):
go run ./cmd/http
# Or: make run-http
# Server runs on http://localhost:3000Building Binaries
make build
# Creates bin/stdio and bin/http🔧 VS Code Integration
This project includes VS Code configuration for seamless development:
1. Open the project in VS Code
2. The MCP configuration is in .vscode/mcp.json
3. Build with Ctrl+Shift+B (or Cmd+Shift+B on Mac)
4. Test the server using VS Code's MCP tools
Using DevContainers
1. Install the Dev Containers extension
2. Open command palette: "Dev Containers: Reopen in Container"
3. Everything is pre-configured and ready to use!
📁 Project Structure
.
├── cmd/
│ ├── stdio/
│ │ └── main.go # stdio transport entrypoint
│ └── http/
│ └── main.go # HTTP transport entrypoint
├── internal/
│ └── server/
│ ├── server.go # Server orchestration
│ ├── tools.go # Tool definitions (hello, get_weather, etc.)
│ ├── resources.go # Resource and template definitions
│ └── prompts.go # Prompt definitions
├── .vscode/
│ ├── mcp.json # MCP server configuration
│ ├── tasks.json # Build/run tasks
│ └── extensions.json
├── .devcontainer/
│ └── devcontainer.json
├── .air.toml # Live reload configuration
├── .golangci.yml # Linter configuration
├── go.mod
├── Makefile
└── README.md🛠️ Development
# Development with live reload (recommended)
make dev
# Requires air: go install github.com/air-verse/air@latest
# Run without live reload
make run-stdio
# Run tests
make test
# Format code
make fmt
# Lint code
make lint
# Install all dev tools
make install-tools
# Clean build artifacts
make cleanLive Reload
Install air for automatic rebuilds:
go install github.com/air-verse/air@latest
make devChanges to any .go file will automatically rebuild and restart the server.
🔍 MCP Inspector
The MCP Inspector is an essential development tool for testing and debugging MCP servers.
Running Inspector
npx @modelcontextprotocol/inspector -- go run ./cmd/stdio/main.goWhat Inspector Provides
- Tools Tab: List and invoke all registered tools with parameters
- Resources Tab: Browse and read resources and templates
- Prompts Tab: View and test prompt templates
- Logs Tab: See JSON-RPC messages between client and server
- Schema Validation: Verify tool input/output schemas
Debugging Tips
1. Start Inspector before connecting your IDE/client
2. Use the "Logs" tab to see exact request/response payloads
3. Test tool annotations (ToolAnnotations) are exposed correctly
4. Verify progress notifications appear for long_task
5. Check that sampling works with ask_llm
📖 Feature Examples
Tool with Annotations
mcp.AddTool(server, &mcp.Tool{
Name: "hello",
Title: "Say Hello",
Description: "A friendly greeting tool",
Annotations: &mcp.ToolAnnotations{
ReadOnlyHint: ptr(true),
},
}, helloHandler)
func helloHandler(ctx context.Context, req *mcp.CallToolRequest, input helloInput) (*mcp.CallToolResult, any, error) {
return &mcp.CallToolResult{
Content: []mcp.Content{
&mcp.TextContent{Text: fmt.Sprintf("Hello, %s!", input.Name)},
},
}, nil, nil
}Resource Template
server.AddResourceTemplate(&mcp.ResourceTemplate{
Name: "Personalized Greeting",
URITemplate: "greeting://{name}",
MIMEType: "text/plain",
}, greetingHandler)Tool with Progress Updates
func longTaskHandler(ctx context.Context, req *mcp.CallToolRequest, input longTaskInput) (*mcp.CallToolResult, any, error) {
progressToken := req.Params.GetProgressToken()
for i := 0; i < 5; i++ {
req.Session.NotifyProgress(ctx, &mcp.ProgressNotificationParams{
ProgressToken: progressToken,
Progress: float64(i) / 5.0,
Total: 1.0,
})
time.Sleep(time.Second)
}
return &mcp.CallToolResult{
Content: []mcp.Content{&mcp.TextContent{Text: "Done!"}},
}, nil, nil
}Tool with Sampling
result, err := req.Session.CreateMessage(ctx, &mcp.CreateMessageParams{
Messages: []*mcp.SamplingMessage{
{Role: "user", Content: &mcp.TextContent{Text: prompt}},
},
MaxTokens: 100,
})🔐 Environment Variables
Copy .env.example to .env and configure:
cp .env.example .env| Variable | Description | Default |
|---|---|---|
PORT | HTTP server port | 3000 |
🤝 Contributing
Contributions welcome! Please ensure your changes maintain feature parity with other language starters.
📄 License
MIT License - see LICENSE for details.
Similar MCP
Based on tags & features
Trending MCP
Most active this week