Go MCP Server Example

A robust Model Context Protocol (MCP) server implementation in Go, featuring analytics reporting tools with idiomatic Go architecture, comprehensive error handling, and enterprise-grade configurability.

Overview

This project demonstrates a well-structured MCP server that provides analytics reporting capabilities by interfacing with external APIs. It showcases modern Go development practices including dependency injection, structured logging, configuration management, and comprehensive error handling.

Features

MCP Protocol Features

1. Tools: Analytics report fetching with configurable parameters
2. Resources: Extensible resource management system
3. Prompts: Interactive prompt system for enhanced user experience
4. Error Handling: Consistent error responses with proper MCP error formatting

Architecture Features

1. Idiomatic Go Structure: Clean separation of concerns with dedicated packages
2. Dependency Injection: Testable components with injectable dependencies
3. Configuration Management: Environment-based configuration with validation
4. Structured Logging: Context-aware logging with slog
5. Type Safety: Generated models from OpenAPI specifications
6. Security: Secure handling of API keys and sensitive configuration

Development Features

1. OpenAPI Integration: Auto-generated models from API specifications
2. Testable HTTP Client: Injectable HTTP client interface for easy mocking
3. Comprehensive Error Handling: All errors returned as MCP-compatible responses
4. Docker Support: Containerized deployment with multi-stage builds
5. VS Code Integration: Configured for seamless MCP server development

Project Structure

go-mcp-example/
├── main.go                        # Entry point and MCP server setup
├── config/                        # Configuration management
├── models/                        # Data types and API models
├── tools/                         # MCP tools implementation
├── prompts/                       # Interactive prompts
├── resources/                     # MCP resources
├── docs/                          # Documentation and setup guides
│   ├── claude-desktop/            # Claude Desktop configuration
│   └── vscode/                    # VS Code configuration
├── .vscode/                       # VS Code project settings
├── .env.example                   # Environment template
├── Dockerfile                     # Container configuration
├── Makefile                       # Development commands
├── openapi.yaml                   # API specification
└── ...                           # Other config files

Architecture Flow

flowchart TD
    A[MCP Client] -->|JSON-RPC| B[MCP Server]
    B --> C{Request Type}
    C -->|Tool Call| D[Tools Package]
    C -->|Resource| E[Resources Package]
    C -->|Prompt| F[Prompts Package]
    
    D --> G[Reports Tool]
    G --> H[API Client]
    H --> I[External API]
    
    G --> J[Config]
    G --> K[Logger]
    
    L[Models] --> G
    L --> H

The MCP server handles three types of operations:

1. Tools: Execute analytics report fetching with configurable parameters
2. Resources: Provide access to static or dynamic resources
3. Prompts: Handle interactive prompts for enhanced user experience

Quick Start

Prerequisites

• Go 1.24+
• US Data Analytics Program API key (Get your API key here)
• Make (optional, for convenience commands)
• Docker (optional, for containerized deployment)

Running the MCP Server

... View full README on GitHub