MCP Demo Server - Educational Implementation Series

A comprehensive three-phase educational implementation of Model Context Protocol (MCP) servers in Go, demonstrating the progression from simple stdio communication to full OAuth 2.1 authentication. This project follows the MCP 2025-06-18 specification and serves as a practical learning resource for understanding MCP concepts and server development.

Overview

This repository contains three complete MCP server implementations, each building upon the previous phase:

1. Phase 1 (stdio/) - Simple stdio-based MCP server
2. Phase 2 (network/) - HTTP network transport server
3. Phase 3 (auth/) - OAuth 2.1 authenticated server

Each phase implements the same core functionality (file reading, directory listing, system information) while adding increasingly sophisticated transport and security features.

Phase Progression

Phase 1: Stdio Transport

• Purpose: Learn MCP fundamentals
• Transport: Standard input/output (stdio)
• Features: Basic tool implementation, JSON-RPC 2.0 communication
• Use Case: Local development, CLI integration
• Directory: stdio/

Phase 2: Network Transport

• Purpose: Understand network-based MCP
• Transport: HTTP with JSON-RPC over HTTP
• Features: HTTP server, concurrent connections, environment configuration
• Use Case: Network services, web integration
• Directory: network/

Phase 3: Authenticated Transport

• Purpose: Production-ready security
• Transport: HTTPS with OAuth 2.1 authentication
• Features: Bearer tokens, security headers, TLS, token validation
• Use Case: Production deployment, secure services
• Directory: auth/

Quick Start

Prerequisites

• Go 1.24.5 or later
• Compatible with MCP 2025-06-18 specification

Running Each Phase

# Phase 1 - Stdio Transport
cd stdio/
go build -o ~/bin/mcp-demo-server-stdio .
mcp-demo-server-stdio

# Phase 2 - Network Transport  
cd network/
go build -o ~/bin/mcp-demo-server-network .
mcp-demo-server-network
# Available at http://localhost:8080

# Phase 3 - OAuth 2.1 Authentication
cd auth/
go build -o ~/bin/mcp-demo-server-auth .
mcp-demo-server-auth
# Available at https://localhost:8443

Testing Each Phase

# Phase 1: Use any MCP-compatible client with stdio transport

# Phase 2: HTTP requests
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

# Phase 3: OAuth 2.1 authentication flow
# 1. Get token
TOKEN=$(curl -s -X POST https://localhost:8443/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" | jq -r '.access_token')

# 2. Use authenticated endpoint
curl -X POST https://localhost:8443/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Available Tools

All phases implement the same three tools:

read_file

• Description: Read the contents of any file from the filesystem
• Parameters: file_path (string, required)
• Example: Read configuration files, source code, logs

list_directory

• Description: List the contents of any directory
• Parameters: directory_path (string, required)
• Example: Explore directory structures, file organization

get_system_info

• Description: Get various system information
• Parameters: info_type (string, required)
  • os: Operating system name
  • arch: System architecture
  • go_version: Go runtime version
  • working_dir: Current working directory
• Example: Environment debugging, system diagnostics

Educational Value

Learning Objectives

1. MCP Protocol Understanding: Learn JSON-RPC 2.0 over different transports
2. Transport Evolution: Understand stdio → HTTP → HTTPS progression
3. Security Implementation: Learn OAuth 2.1 aut

... View full README on GitHub