01-basic-mcp

Basic MCP Server Example

This example demonstrates how to implement a basic Model Context Protocol (MCP) server in Go, supporting multiple transport modes (stdio and HTTP) and using the Gin web framework for HTTP routing.

Overview

The server.go file provides a minimal yet extensible MCP server that:

• Registers a common tool (see operation.RegisterCommonTool)
• Supports two transport types: stdio and HTTP
• Uses Gin for HTTP routing and middleware
• Demonstrates best practices for server setup, logging, and error handling

Directory Structure

01-basic-mcp/
├── server.go
└── README.md   ← (this file)

Key Components

MCPServer Struct

Encapsulates the MCP server instance and provides a method to expose it as an HTTP handler.

type MCPServer struct {
    server *server.MCPServer
}

Server Initialization

The NewMCPServer function creates and configures the MCP server, enabling tool capabilities, logging, and recovery middleware. It also registers a common tool for demonstration.

func NewMCPServer() *MCPServer

Transport Modes

The server can be started in one of two modes, controlled by the -transport flag:

• stdio: Communicates via standard input/output (for CLI or local integration)
• http: Runs as a standard HTTP server using Gin

Command-Line Flags

Flag	Default	Description
-addr	:8080	Address to listen on (for HTTP mode)
-transport	stdio	Transport type: stdio or http
-t	(none)	Alias for -transport

Usage

Prerequisites

• Go 1.24 or later
• Required dependencies (see go.mod)

Running the Server

1. Clone the repository and navigate to the 01-basic-mcp directory.

2. Build and run the server:

go run server.go -transport http -addr :8080

Example: Start with stdio transport

go run server.go

Example: Start with HTTP transport

go run server.go -transport http -addr :8080

HTTP Endpoints (when using -transport http)

• POST /mcp
• GET /mcp
• DELETE /mcp

All handled by the MCP server via Gin.

Code Structure

• Server Initialization: Sets up the MCP server with middleware and registers tools.
• Transport Selection: Chooses the transport based on the -transport flag.
• HTTP Routing: Uses Gin to route /mcp requests to the MCP server handler.

Example: Minimal Main Function

func main() {
    // Parse flags
    // Create MCPServer
    // Switch on transport type:
    //   - stdio: server.ServeStdio
    //   - http:  Gin router with /mcp endpoint
}

Extending the Example

• Register additional tools by calling their registration functions with the MCP server instance.
• Add custom middleware to the Gin router for authentication, logging, etc.
• Integrate with other transports as needed.

References

• mark3labs/mcp-go — MCP Go SDK
• gin-gonic/gin — Gin web framework

License

This example is provided under the MIT License.