MCP Tools Server

A Go-based Model Context Protocol (MCP) server that provides simple tools for AI assistants.

Features

• UUID Generation Tool: Used as an Example. Generates random UUID v4 strings via MCP protocol
• Multiple Protocol Support: Works with MCP (stdio), HTTP REST API, Streamable HTTP, and WebSockets.
• Graceful Shutdown: Handles system signals properly for clean termination
• Concurrent Requests: Supports multiple simultaneous tool calls
• Comprehensive Testing: Unit, integration, and contract tests included
• Makefile Automation: Convenient build, test, and run commands
• Extensible Architecture: Easily add new tools by implementing the Tool interface
• Tiny Footprint: A singe 5.8MB compiled binary or a 15MB Docker image
• Prometheus Metrics: Built-in metrics for monitoring server performance

Installation

Prerequisites

• Go 1.24.6+ (as specified in go.mod)
• Make (for using the Makefile commands)

Setup

git clone <repository-url>
cd mcp-tools-server
go mod tidy
make build

Usage

Using Makefile Commands

The project includes a Makefile for common operations:

• make build: Build the application binary.
• make run or make run-all: Run all servers (default).
• make run-http: Run only the HTTP REST server.
• make run-mcp: Run only the Stdio MCP server.
• make run-streamable: Run only the Streamable HTTP server.
• make run-websocket: Run only the WebSocket server.
• make test: Run all tests.
• make clean: Remove build artifacts.
• make lint: Run the Go linter.
• make help: Show all available commands.

Running the Server

You can control which servers to run using command-line flags. By default, all four servers (Stdio MCP, HTTP REST, Streamable HTTP, and WebSocket) are enabled. You can also use the make targets (make run-http, make run-mcp, etc.) as a convenient shortcut for these commands.

• Run all servers (default):

  ./build/server
  # or
  ./build/server --all
  

• Run only the HTTP REST server:

  ./build/server --http
  

• Run only the Stdio MCP server:

  ./build/server --mcp
  

• Run only the Streamable HTTP MCP server:

  ./build/server --streamable
  

  The streamable server runs on port 8081 by default.

• Run only the WebSocket server:

  ./build/server --websocket
  

  The WebSocket server runs on port 8082 by default.

• Show version info:

  ./build/server --version
  

As MCP Server

The server communicates via stdio for MCP clients (typically used by AI assistants):

./build/server --mcp

Streamable HTTP MCP

The server now supports the official Streamable HTTP transport from the MCP specification. This runs on port 8081 by default and provides a single /mcp endpoint for all communication.

• Making a tool call (POST):

  curl -X POST http://localhost:8081/mcp \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tools/call",
      "params": {
        "name": "generate_uuid"
      }
    }'
  

  The server will return a JSON-RPC response immediately.

• Listening for server-sent events (GET): This opens a persistent Server-Sent Events (SSE) stream.

  curl -N http://localhost:8081/mcp
  

  The server can now push messages to the client over this connection.

HTTP API

The server exposes a simple REST API on port 8080 for basic tool interaction. For testing, run in HTTP-only mode:

./build/server --http &
curl http://localhost:8080/api/uuid

Response:

{"uuid": "550e8400-e29b-41d4-a716-446655440000"}

API Documentation

Endpoints

GET /api/uuid

Generates and returns a random UUID v4 string.

Request:

curl http://loca

... [View full README on GitHub](https://github.com/lkendrickd/mcp-tools-server#readme)